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Preface 


Manual Objectives 


This manual describes the DECnet/E services available to a BASIC program- 
mer, permitting him to code programs that exchange data with other pro- 
grams running in a DECnet network. Hither the BASIC-PLUS or the BA- 
SIC-PLUS-2 languages can be used. 


Intended Audience 


This manual is written for the experienced programmer. While the reader is 
not expected to be knowledgeable of network programming, he is expected to 
be completely familiar with both the BASIC programming language and the 
general mechanisms for interfacing with the RSTS/E operating system. 


Prerequisite Reading 


The reader is expected to be completely familiar with the concepts and fea- 
tures of the BASIC programming languages, as presented in the following 
manuals: 


BASIC-PLUS Language Manual 
BASIC-PLUS-2 Language Manual 


The RSTS/E BASIC-PLUS-2 User’s Guide gives instructions on how to com- 
pile BASIC programs in a RSTS/E system. The RSTS/E Task Builder Man- 
ual describes TKB, the linker used for building RSTS/E tasks from compiled 
BASIC programs. 


The reader is also expected to be familiar with the concepts and features 
available for interfacing to the RSTS/E system monitor, as presented in the 
following manuals: 


RSTS/E System User’s Guide 
RSTS/E Programming Manual 


Related Documents 


To obtain a general understanding of the DECnet environment — internal 
and external — the reader is directed to the Introduction to DECnet. 


Vii 


viii 


DECnet/E also provides utility programs that allow a terminal user to com- 
municate with another terminal user, to manipulate files across the network, 
and to copy the contents of one storage device to a device on another system. 
The information needed to run and use these utilities is given in the compan- 
ion manual, DECnet/E Guide to User Utilities. 


Two other companion manuals tell how to generate and start a DECnet/E 
system (the DECnet/E System Installation Guide), control and manage a 
running DECnet/E system (the DECnet/E System Manager’s Guide), and 
give other information useful to a system manager. 


Three more DECnet/E manuals are available describing the DECnet/E mes- 
sage send/receive services for three other languages: 


DECnet/E Network Programming in MACRO-11 
DECnet/E Network Programming in FORTRAN 
DECnet/E Network Programming in COBOL 


The more advanced network programmer may want to refer to the following 
two manuals for information concerning various network management func- 
tions: 


DIGITAL Network Architecture, Network Services Functional 
Specification 

DIGITAL Network Architecture, Network Management Functional 
Specification 


Structure of This Manual 


This manual is divided into four main parts. Part I, “Introduction,” presents 
a general discussion of the DECnet/E environment (Chapter 1). Part II, 
“Background Concepts for Network Programming,” presents a tutorial dis- 
cussion of the DECnet/E features available for sending and receiving mes- 
sages (Chapters 2 through 4). Part III, “Network Programming in BA- 
SIC-PLUS,” describes the SYS call formats used to access those features 
from BASIC-PLUS (Chapter 5), and Part IV, “Network Programming in 
BASIC-PLUS-2,” describes the subroutine call formats used from BA- 
SIC-PLUS-2 (Chapter 6). 
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Introduction 








Chapter 1 
Introduction 


DECnet/E is a combination of hardware and software that extends the capa- 

bilities of a RSTS/E system running on a DIGITAL PDP-11 computer to 

allow a programmer to develop and execute programs that exchange data with 
Cc remote programs running on another DECnet system in a network. 


NOTE 


Throughout this manual, the term remote program refers to 
any other program with which a program is communicating 
using the DECnet facilities. Such programs need not be located 
on another node in the network. It is possible to use DECnet/E 

Cc to communicate with other programs at the local RSTS/E 
node. During development of network application programs, 
the whole system can be debugged locally and later distributed 
to remote nodes as required. 


This manual describes the features available to network programmers in the 
BASIC-PLUS and BASIC-PLUS-2 programming languages on RSTS/E sys- 
tems. 


c 


1.1 Basic Terms and Concepts 


The term network is used here to refer to two or more computer systems 
connected such that they can exchange information. The computer systems, 
called nodes, are connected by communications paths called physical links. 
Physical links can be established through normal (switched) telephone cir- 
cuits, several varieties of leased (private) lines, coaxial cables, or even satellite 
transmission facilities provided by several carriers. 


In the network shown in Figure 1-1, a user at node BOSTON would refer to 

BOSTON as the local node and to nodes DENVER, DALLAS, LONDON, 

and LA as remote nodes. At node BOSTON, the nodes DENVER, DALLAS, 

and LONDON are physically adjacent nodes. That is, there is a direct physi- 

cal link to these nodes with no intervening nodes. To a user at node LA, 
@ DENVER is the only adjacent node. 


A path is the route over which data travels from its source to its destination 
within the network. Path length is the distance from the source node to the 
destination node, measured in hops. A hop is equal to a physical line between 
two adjacent nodes. In Figure 1-1, the path length between nodes DALLAS 
and BOSTON is one hop and between LA and LONDON is three hops. The 
network diameter is the maximum path length between any two nodes. The 
network shown in Figure 1-1 has a network diameter of three hops. 


Transmit Via Satellite 
(Physical Link) 






P Node 
~ BOSTON 





Node 
DALLAS 


Figure 1-1: Computer Network Composed of Five Nodes 


1.2 DECnet Networks 
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DECnet as a whole refers to the hardware and software that allows different 
DIGITAL systems to be connected to form networks. DECnet has been de- 
signed to allow each system to function as a separate entity but still allow 
access to resources that are distributed throughout the various systems in the 
network. A DECnet/E system provides all the capabilities of a normal 
RSTS/E system as well as the networking capabilities described in this man- 
ual and in the companion DECnet/E manuals listed in the Preface. 


All DECnet implementations are based on a design structure called the DIGI- 
TAL Network Architecture (DNA). This architecture allows network imple- 
mentations on the various DIGITAL systems to evolve (to provide more and 
more capability as time goes on) within a basic common structure. The struc- 
ture ensures that implementations providing fewer features will always work 
with implementations providing more. 


Perhaps a more immediate aspect of this process of evolution, however, is that 
at any given time capabilities can indeed differ from system to system. We do 
not attempt to describe here the DECnet implementations for all the different 
DIGITAL systems. Nevertheless, to use DECnet/E, you do need to give some 
thought to the other DIGITAL systems in your network. 
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If your network consists entirely of DECnet/E Version 2.0 nodes, this docu- 
ment provides all the information necessary for you to use DECnet/E to send 
and receive messages in BASIC programs. If your network contains other 
DECnet systems, however, you should check the DECnet documentation for 
those systems to be sure that the corresponding capabilities exist. For exam- 
ple, you can design network programs to be started automatically on RSTS/E 
systems. This feature is not available on all DECnet systems, however, so 
your design should not necessarily assume this capability. 


A brief overview of the functional capabilities of the various DECnet imple- 
mentations can be found in Introduction to DECnet. 


1.3 The DIGITAL Network Architecture (DNA) 


DECnet/E is implemented according to a set of rules, or protocols, governing 
the format, control, and sequencing of data exchange from the user program 
level down through the physical link level. These protocols are defined by the 
DIGITAL Network Architecture (DNA) — a logical structure that provides 
the model for all DECnet implementations. 


DNA consists of several layers, each defining a distinct set of network func- 
tions and a set of rules for implementing those functions, Each DECnet im- 
plementation consists of software modules that perform these DNA-defined 
functions according to DNA-defined protocols. The relevant protocols for net- 
work programming are called the Network Services Protocol (NSP), the 
Transport protocol, and the Digital Data Communications Message Protocol 
(DDCMP). 


The Network Services Protocol defines the rules for communication between 
programs in a network over paths called logical links. Logical links, described 
in detail in Chapter 2, allow many different data streams to be multiplexed 
onto the physical link for transmission and separated at the receiving node for 
delivery to the appropriate program. 


The Transport protocol defines the rules for determining the actual physical 
path, or route, along which data travels to its destination. 


Physical link control is achieved in DECnet by implementation of the Digital 
Data Communications Message Protocol (DDCMP). DDCMP ensures an er- 
ror-free, sequential data path over a generally error-prone medium, This is 
accomplished with the Cyclic Redundancy Check (CRC) for error detection, 
retransmission for error corrections, and numbered data segments to ensure 
sequential transmission of data. 


1.4 Network Routing 


DECnet/E Version 2.0 is a Phase III DECnet product. (Refer to Introduction 
to DECnet for a discussion of the differences between Phase II and Phase III 
DECnet products.) As such, it supports the adaptive routing feature of Phase 
Ill, providing the user with the capability of communicating with other nodes 
in the network regardless of whether or not they are directly connected to the 
local node. 
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Networks can consist of the following three types of nodes: 


e Routing nodes — Phase III nodes connected to multiple communications 
lines, supporting route-through capabilities 


* Nonrouting nodes (end nodes) — Phase III nodes connected to a single 
communications line 


¢ Phase II nodes — nodes running a previous generation of the DECnet 
architecture 


Phase III nodes can communicate with and are compatible with Phase II 
nodes. However, Phase II nodes do not acquire any new capabilities by being 
connected to Phase III nodes, and the restriction that Phase II nodes can only 
communicate with adjacent nodes continues to apply. Thus, a Phase III node 
can communicate with any other Phase III node, providing the path goes 
through Phase III nodes only. 


The adaptive routing feature is implemented through an algorithm that 
chooses the routing path with the lowest associated cost. Cost is computed as 
the sum of the costs of the lines over which the message is transmitted. The 
individual line cost parameters are assigned by the system manager and input 
into the system with the Network Control Program. (See the DECnet/E Sys- 
tem Manager’s Guide for a full discussion of line costs.) The algorithm auto- 
matically adjusts the routing when network topology or line cost changes 
occur. 


1.5 Overview of DECnet/E Structure 
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The DECnet/E features for network communication are implemented as part 
of the RSTS/E system monitor. The manner in which these features are 
accessed differs with the type of user. 


User programs interface with DECnet/E through NSP. Although it is not a 
separate entity or program, the term NSP is used throughout this manual to 
refer to the software that allows a user program to establish and exchange 
data over logical links. In other words, NSP is the implementation of the 
Network Services Protocol. The RSTS/E BASIC-PLUS programmer accesses 
NSP services directly, via SYS calls to the RSTS/E system monitor. In BA- 
SIC-PLUS-2, the programmer codes calls to MACRO-11 (assembly lan- 
guage) subroutines to use NSP. These subroutines can also be called from 
MACRO-11, FORTRAN, or COBOL programs, as described in associated 
DECnet/E Network Programming Manuals. 
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Terminal users access certain network capabilities through various DEC- 
net/E utility programs. The utilities TLK (Talk) and LSN (Listen) allow two 
terminal users to type messages to each other. The utilities NFT (Network 
File Transfer) and FAL (File Access Listener) work together to allow network 
file manipulation. They are implemented according to the Data Access Proto- 
col (DAP) so that files can be exchanged with other DECnet systems having 
the same capabilities. The NET utility allows the terminal user to log into 
and use a remote RSTS/E system as though the local terminal were directly 
connected to the remote system, and NETCPY copies entire devices between 
RSTS/E nodes. (See the DECnet/E Guide to User Utilities for details on these 
utility programs.) 


The system manager uses the features provided by the Network Control 
Program (NCP) to monitor and control a node running in a network. (See the 
DECnet/E System Manager’s Guide for details on running NCP.) 


Some elements of DECnet/E are not directly accessible to any user. These 
lower level elements of DECnet/E include the network Transport module 
(TRN) that implements the Transport protocol, several hardware devices (the 
DMC11, DMR11, DMV11, and DMP11), and their associated software device 
drivers. 


The device drivers are responsible for handling messages received from and 
sent over the physical communication lines. NSP gives a message to be sent to 
Transport, which selects an appropriate data path based on the destination of 
the message. Transport then passes the message to the proper device driver 
for actual transmission. The drivers manipulate the device registers to cause 
message transmission to occur, 


To handle incoming messages, the drivers include buffer management func- 
tions that allow messages to be received from the physical links. When a 
message is received, it is passed to Transport, which checks the destination of 
the message. If the message is for the local node, Transport passes it to NSP 
for further processing. If the message is destined for another node in the 
network, Transport selects a data path and passes the message to one of the 
drivers for transmission. 


The hardware devices are intelligent communication controllers that connect 
the PDP-11 to physical communications lines. The DMC11 and the DMR11 
control lines that connect to only one other system in the network (point-to- 
point lines) while the DMV11 and the DMP11 control lines that may connect 
to more than one other system (multipoint lines). The physical lines can 
include cables, modems and telephone circuits, or even satellite transmission 
facilities. Each controller contains a microprocessor, its own memory, and 
microcode that implements the DDCMP protocol. The implementation of 
DDCMP in firmware considerably reduces the software overhead for the 
DECnet/E system. 
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Network Programming 


Chapter 2 
Logical Links 


This chapter introduces the logical link — the basic element of DECnet task- 
to-task communication. A logical link is a software path for the exchange of 
data between two programs running in a network. 


In a network of DECnet nodes, many programs use the same physical path to 
exchange data. Data being sent from one program to another over a logical 
link is interspersed (multiplexed) with data sent over other logical links, 
transmitted over the physical line, and separated (demultiplexed) at the re- 
ceiving end. The Network Services Protocol (NSP), implemented as a part of 
the DECnet software at each node, handles this multiplexing and demulti- 
plexing. It accepts outgoing data from local programs and formats it for trans- 
mission by the communications hardware. NSP also accepts incoming data 
from remote nodes and separates it into individual logical link streams which 
are then delivered to the appropriate local programs (see Figure 2-1). 


LOCAL NODE REMOTE NODE 


all outgoing data 





Figure 2-1: NSP Handles Multiplexing and Demultiplexing of Data over 
Physical Lines 
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Throughout the remainder of this chapter, and the two chapters that follow, 
various logical link parameters are discussed — object name and type code, 
local and remote logical link address, flow control data request counts, and so 
on. These parameters can be observed on an operational node by issuing the 
NCP SHOW LINK command (for a single link) or the SHOW ACTIVE 
LINKS command (for all current links). This can be very helpful when debug- 
ging a network program. (See the DECnet/E System Manager’s Guide for 
details on using these NCP commands.) 


2.1 Creating a Logical Link 
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Creating a logical link is a cooperative venture. Two programs must agree to 
communicate before a logical link is established. The procedure is basically 
the same for all implementations of DECnet. The program that initiates the 
request for a logical link connection is called the source. The other program is 
called the target. This distinction is made only during the connection se- 
quence. 


NOTE 


Other network implementations make the source program the 
“link master”. The source must poll the target for data and 
only the source can disconnect the link. DECnet does not make 
this distinction. Once the connection is established, the terms 
“source” and “target” have no significance and both the local 
and remote programs have equal access to the logical link. 


The request for a connection takes the form of a Connect Initiate Message 
that includes detailed information identifying the remote node and target 
program to which the connection is to be made. It also establishes an identi- 
fier for the link itself. In DECnet/E, the link identifier is called a user link 
address, or ULA. A ULA is a number from 1 to 255 that is used by the source 
program to refer to the link during subsequent send and receive operations. 


The NSP software at the source node does some initial checking of the request 
(to determine if it recognizes the remote node, for example). If all is well, the 
source NSP forwards the connect request to the NSP at the target node. The 
target NSP does its own checking to determine if the connection can be made. 
If the connection cannot be made, the target NSP rejects the connection. 
Otherwise, it delivers the connect request to the target program. The target 
program may then choose to accept or reject the logical link. 


If the target program accepts the link, it selects its own link identifier by 
which it will refer to the link. The two link identifiers are unrelated to one 
another. They can even take quite different forms if the programs are written 
in different languages or for different operating systems. If the remote node is 
a DECnet/E node, this identifier is again called a user link address and can 
range from 1 to 255. The number selected is completely independent of the 
selection made by the source program. The source and target NSPs relate the 
two identifiers to the same logical connection and keep the data exchanged 
over the link separate from data exchanged over other logical links. 
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The target program’s confirmation or rejection of the link is passed back over 
the network to the source NSP, which passes this information on to the source 
program. This confirmation or rejection takes the form of a Connect Confirm 
or Connect Reject Message that is queued for the source to receive and pro- 
cess. 


If the connection is confirmed after this mutual handshaking, the two pro- 
grams can then send and receive data over the link, each referring to the link 
by the identifier it assigned during the connection sequence. Both programs 
can send data simultaneously, since the DECnet software provides logical full 
duplex transmission regardless of the characteristics of the intervening net- 
work. Either program can break the logical link connection when it is no 
longer needed. 


In Figure 2-2, A shows the procedure for establishing a logical link connection. 
The target NSP considers the link “up” (that is, it will allow the target 
program to send data) when the source NSP has acknowledged receipt of the 
Connect Confirm Message. The source NSP considers the link up when it 
receives the Connect Confirm Message. In Figure 2-2, B, C, and D illustrate 
the three ways in which a request for a link might be rejected. 


2.2 Advantages of Logical Links 


In addition to making it possible to sort out the many physical streams of data 
that pass over a single physical line, the logical link structure maintained by 
NSP has several other advantages. 


e Reduction of addressing data required for message transmission, thereby 
providing efficient line usage 


e Separation of data into separate message streams 
e Provision for high-priority “Interrupt” messages 


e Ability to control the flow of data, thereby relieving possible network 
congestion 


2.2.1 Efficient Line Usage 


Once established, a logical link simplifies the addressing necessary for the 
exchange of data between two programs, both at the user’s level and in trans- 
mission of data across the network. As mentioned previously, a link identifier 
is assigned by each program to identify an established logical link. This iden- 
tifier is more convenient than the longer, detailed address used in identifying 
the remote node and program in the original Connect Initiate Message. 


During a connection sequence, the source NSP and target NSP also establish 
a set of addresses that they use to identify the logical link. These addresses are 
called the local link address (LLA) and the remote link address (RLA), re- 
spectively. Each NSP refers to its own as the local link address and the other 
as the remote link address. 
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A. Remote program confirms logical link connection 


LOCAL NODE REMOTE NODE ‘ 
| want to talk 
with PROGB at 


Node DENVER. 














CONNECT INITIATE 






LOCAL NODE REMOTE NODE 







CONNECT CONFIRM 


B. Local NSP returns an error on connect request 


LOCAL NODE 






| want to talk 
with PROGB at 
Node DENVER, 







C. Remote NSP rejects logical link connection 


LOCAL NODE REMOTE NODE 






$ want to talk 
with PROGB at 
Node DENVER. 







CONNECT INITIATE 





LOCAL NODE REMOTE NODE 


Nobody here 
by that name. 


CONNECT REJECT 





Figure 2-2: Logical Link Connections 2 
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D. Remote program rejects logical link connection 


LOCAL NODE REMOTE NODE 


os 
| ws, 


LOCAL NODE REMOTE NODE 












| want to talk 
with PROGB at 
Node DENVER. 











CONNECT INITIATE 


CONNECT REJECT 


Figure 2-2 (Cont.): Logical Link Connections 


While individual ULAs must be unique to the source program and to the 
target program, they are by no means required to be unique throughout the 
network, or even within the local node. Thus, the LLA and the RLA are 
required by NSP to separate the many distinct message streams that are 
multiplexed onto the communications lines. Since each NSP’s LLA is unique 
to its own node, these NSP addresses reduce the amount of control and identi- 
fying information that must accompany the user data transferred across the 
link (see Figure 2-3). 


Figure 2-4 illustrates how these addresses work, showing two DECnet/E nodes 
with two established logical links. Program A, for example, has established a 
logical link with Program D. Program A refers to the link with a user link 
address of 1. Program D refers to the link with a user link address of 23. Each 
NSP has established its own local link address. For Program A’s NSP, the 
LLA is 123456. For Program D’s NSP, the LLA is 024602. Each NSP keeps 
track of the other’s LLA as a remote link address. 


A. Message sent across the line for a connect request 


CONTROL AND ADDRESSING USER DATA 


B. Data message sent across the line over a logical link 


CONTROL AND ADDRESSING USER DATA 


Figure 2-3: Logical Links Provide Line Efficiency 
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LOCAL NODE REMOTE NODE 


NSP 
Line 
LLA RLA_ No. 
021357 





Chae 
2 a ee aaa 


Figure 2-4: User Link Addresses, Remote Link Addresses, and Local 
Link Addresses for Logical Links 


2.2.2 Separate Data by Intended Use 


Logical links provide a means by which incoming messages can be separated 
into different message streams. A program can establish different logical links 
to communicate with different remote programs. Or it can establish several 
logical links with the same remote program to exchange data intended for 
different purposes. 


Before a program can use the message services, it must first register this 
intention with NSP. This involves declaring the name by which the program 
is to be known to other remote programs in the network (that is, its identity), 
as well as any limits or restrictions that will affect the way in which the 
program can use the message services. 


When a program declares its intent to use the network message services, NSP 
sets up a receive queue to hold pending messages. Thereafter, all messages 
received for the program are placed in the queue. Messages from different 
logical links are interspersed in the queue but the receiving program can 
retrieve either the first message in the queue or the first message from a 
particular logical link. 


The concept of separate message streams for separate logical links is illus- 
trated in Figure 2-5. 
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Figure 2-5: Data Is Queued for Logical Links in Separate Streams 


2.2.3 Interrupt Messages 


Special high-priority Interrupt Messages can be sent over logical links in all 
DECnet implementations. DECnet/E queues incoming Interrupt Messages at 
the head of the pending message queue, behind the first message in the queue 
(since the user program could be in the process of retrieving the first message) 
and behind any other pending Interrupt Messages queued for the program. 


In the DECnet/E implementation, these Interrupt Messages are not true in- 
terrupts in the sense of causing an immediate jump to an interrupt processing 
routine. (Some DECnet implementations do treat Interrupt Messages as true 
interrupts.) They are simply messages that can be identified as different from 
ordinary data messages and that are placed at the head of the pending mes- 
sage queue (see Figure 2-6). 


If a program is designed to send Interrupt Messages, the receiver at the other 
end of the link must be set up to process them. Interrupt Messages can 


contain a small amount of user data so that programs can be designed to 
recognize Interrupt Messages for different purposes. 


Interrupt Messages are discussed in more detail in Chapters 3 and 4. 
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Figure 2-6: Queuing of Interrupt Messages for Logical Links 


2.2.4 Flow Control 


NSP maintains each program’s queue of pending messages in system buffer 
space. A message is stored in the queue until it is received by the user pro- 
gram. Thus, pending messages tie up valuable system resources. Several flow 
control mechanisms are used in DECnet to protect systems from being flooded 
with messages. Some of these mechanisms are system-regulated while one 
mechanism is selected and controlled by the user program. 


Each receiver program can select one of the following three types of program- 
regulated flow control: 


¢ Segment flow control 
¢ Message flow control 


e No active flow control 


A discussion of program-regulated flow control is given in Section 4.2.3. 


2.3  DECnet/E Logical Link Limitations 
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The implementation of DECnet for RSTS/E allows a maximum of 127 active 
logical links for the entire node at any one time. The system manager can 
reduce this maximum to some number between 1 and 127. There is no limit to 
the number of logical links per program other than the system maximum. 


Network Programming in BASIC-PLUS and BASIC-PLUS-2 


Chapter 3 
Overview of DECnet/E Message Services 


RSTS/E provides message services for communication between local pro- 
grams. The DECnet/E message services are implemented as an extension of 
these local services. In addition, DECnet/E offers new capabilities for local 
communication not found with the original RSTS/E message mechanism. The 
original local communication services are described in the RSTS/E Program- 
ming Manual. They are repeated in this document both for completeness and 
because they are the logical basis for the DECnet extensions. 


We emphasize here that it is the way in which the user interfaces with DEC- 
net from RSTS/E that is implemented as an extension of local capabilities. 
An RSX-11 programmer might interface with DECnet somewhat differently. 
The underlying architecture provides the consistency. The programmer at 
each system uses a familiar language and form. DECnet handles both the 
transmission itself and the translation necessary at both nodes to convert the 
original call to a form that can be transmitted over the line and back to the 
format expected at the receiving node. 


Table 3-1 lists the calls used for interprogram communication by programs 
running under DECnet/E. The remaining sections of this chapter give a gen- 
eral description of each of the calls. Specific BASIC calls, with detailed for- 
mats, are given in Chapters 5 and 6. 


Table 3-1: Summary of Calls for Interprogram Communication 


Call Function 

Declare Receiver Registers the program with the operating system for 
message services. 

Remove Receiver Terminates message operations for the program. 

Get Local Node Parameters Obtains local node information. 

Log User Event Queues a user-generated event to the local event proc- 


essor for logging. 


Send Local Data Message Transmits user data to a local program. 


(continued on next page) 
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Table 3-1 (Cont.): Summary of Calls for Interprogram Communication 


Call Function 
Send Connect Initiate Message Requests a logical link connection with another pro- 
gram. 


Send Connect Confirm Message Accepts a logical link connection requested by another 


program. 

Send Connect Reject Message Rejects a logical link connection requested by another 
program. 

Send Network Data Message Transmits user data to a network program over an es- 
tablished logical link. 

Send Interrupt Message Transmits interrupt data to a network program over an 
established logical link. 

Send Link Service Message Requests data over a flow controlled logical link. 

Send Disconnect Message Disconnects an established logical link, after all pend- 


ing messages have been sent. 


Send Link Abort Message Disconnects an established logical link immediately, 
destroying any messages waiting to be sent. 


Receive Receives a message from the queue of pending mes- 
sages. (One of nine message types, corresponding to the 
nine Send calls listed above, could be received.) 


3.1 General Remarks 
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The Declare Receiver call informs the local RSTS/E monitor that the program 
issuing the call intends to communicate with other programs. This call identi- 
fies the program and defines which of the services will be required. The Re- 
move Receiver call is issued when message operations are complete for the 
program and releases system resources used for message services. The Get 
Local Node Parameters call returns information to the calling program con- 
cerning the local node. The Log User Event call permits a user-written pro- 
gram to queue an event to the local event processor for logging. 


Beyond these, the operations available fall into two categories: send and re- 
ceive. The entities sent and received are called messages. They consist of 
control information identifying the type of message, and in most cases, data of 
interest to the programs exchanging information. Nine message types are 
available for these operations. 


A separate call is used to send each of the message types. That is, there is a 
Send Connect Initiate Message call, a Send Local Data Message call, and so 
forth. When one of these calls is executed, NSP uses the parameters and user 
data included in the call to format the appropriate network message into 
system buffer space. Necessary header information is also included. This mes- 
sage is then queued to Transport for transmission across the network. The way 
in which a message is queued for transmission depends on the type of mes- 
sage. (A discussion of transmission queuing is given in Section 4.2.1.) 


Network Programming in BASIC-PLUS and BASIC-PLUS-2 


2 


2 





The Receive call retrieves a message from the program’s queue of pending 
messages maintained by NSP in system buffer space. NSP queues incoming 
messages for the program as they come in across the network. Messages from 
local senders are also placed in the pending message queue. 


NOTE 


Within the current context, local programs are programs run- 
ning at the local node that send messages using only the Send 
Local Data Message call. Network programs, on the other 
hand, are programs running either locally or remotely that use 
DECnet to establish and send data over logical links. 


The Receive call returns control information identifying the sender and the 
type of message (one of the nine listed previously in Table 3-1). User data 
accompanying the message is returned to a user buffer specified in the Receive 
call where it can then be examined and processed. 


A user program can issue general or selective Receive calls. On a general 
Receive call, the first message in the queue is returned. A selective Receive 
call can select the first message from any local sender, a particular local 
sender, any network sender, or a particular logical link. 


There can be times when no pending messages are in the queue when a 
Receive call is issued. One option available in the Receive call causes the 
program to “sleep”, or suspend execution, until some action takes place — 
until a message is queued or a specified amount of time has passed, for 
example. The Receive call can also be issued to retrieve only part of a mes- 
sage. A program with limited buffer space can choose to retrieve only part of 
the user data with one Receive call. Subsequent Receive calls will retrieve the 
rest of the data, or the remaining data can be discarded. 


3.2 Registering with the Monitor: Declare Receiver Call 


A program declares its intent to use the message services by issuing a Declare 
Receiver call. This call must be executed before a program can send network 
messages or receive messages of any type. A program can, however, send local 
data messages without executing this call. 


The Declare Receiver call does more than just declare intent, however. It also 
defines the way in which other programs throughout the network are to ad- 
dress this program (the program’s identity) and the way in which the program 
can thereafter use the message services. 


The Declare Receiver call has some rather far-reaching effects. For this rea- 
son, the parameters specified with the call and how the system uses them are 
described here in detail. 


3.2.1 Declaring Identity 


A Declare Receiver call identifies the calling program with an object type 
code, a name, or both. The manner in which a program declares its identity 
affects the way incoming link connections are handled. 
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A name is an ASCII identifier that can be used by either local or network 
programs to refer to the declarer. No two programs at the local node can use 
the same name at the same time. If a name is given, it must be unique within 
the local node. 


An object type code, on the other hand, is simply a number in the range of 1 to 
255. It can be used by other network programs to refer to the declarer. (Local 
programs cannot address a receiver by object code.) These codes simplify the 
identification of programs performing identical functions at different nodes of 
a network, without going through the cumbersome process of arriving at and 
enforcing standard naming conventions. 


An object code also need not be unique, and more than one receiver can 
declare identity with the same object code simultaneously. A program per- 
forming a general-purpose function of interest to the entire network can incur 
heavy use. By permitting more than one program to declare identity with the 
same object code at the same time, DECnet/E permits execution of multiple 
copies of a program to meet sporadic heavy usage. 


A range of object type codes (1 through 127) is reserved for DECnet use. The 
remainder (128 through 255) are available for user applications programs. 
Currently assigned object type codes for DECnet use are given in Appendix A. 


NOTE 


In the DECnet environment it is recommended that, whenever 
possible, programs declare their identity with and be addressed 
by nonzero object type codes. 


Network addressing is discussed in detail in Chapter 4. 


3.2.2 Declaring Intended Usage 


In addition to identifying the program, the Declare Receiver call defines how 
the program intends to use the message services. For example, a program can 
limit the incoming messages to those from local senders only. Or, it can limit 
incoming messages to those from network senders only. 


Other protective limits can be set in the Declare Receiver call. 


¢ The maximum amount of system buffer space to be used for the pending 
message queue 


¢ The maximum number of messages that can be stored in the pending mes- 
sage queue 


¢ The maximum number of active logical links that the program can have at 
any given time 


These limits affect incoming messages and incoming requests for logical links. 
The Declare Receiver call does not limit the type or number of send calls a 
program can execute. 
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3.2.3 DECnet/E Use of the Declare Receiver Call 


When a Declare Receiver call is issued, the system sets up a 32-byte Receiver 
ID Block (RIB) to associate the information with the RSTS/E job number. 
The Receiver ID Block actually applies to the job rather than the program 
that issues the Declare Receiver call. This distinction is rather fine for most 
applications, but does make it possible, for example, to chain together a set of 
programs using message services. The first program in the series would exe- 
cute a Declare Receiver call. Then other programs in the chain would also be 
valid receivers as long as they were always executed under the same job 
number. 


The Receiver ID Block holds the arguments passed with the Declare Receiver 
call, along with other system- and NSP-maintained information, such as the 
address pointers of the pending message queue and the address of the list of 
active logical links. 


3.3 Remove Receiver Call 


A Declare Receiver call remains in effect until a Remove Receiver call is 
issued. The Remove Receiver call releases the Receiver ID Block. All pending 
messages are discarded and all active logical links are destroyed. (NSP sends 
a Link Abort Message to the remote programs for any active logical links.) 


Like the Declare Receiver call, the Remove Receiver call applies to the 
RSTS/E job. If a program does not issue a Remove Receiver call before termi- 
nating execution, other programs executed later under this job number will be 
unable to issue a Declare Receiver call. (As far as the system is concerned, the 
old one is still in effect.) A Remove Receiver call should be issued as soon as 
message services are no longer needed. This practice prevents queuing of 
unwanted messages and releases the system buffer space used for the Receiver 
ID Block. 


Also, any program that could be stopped by a terminal user’s should 
have provisions to issue a Remove Receiver call and terminate gracefully. If a 
job is killed, NSP automatically destroys any active logical links, discards 
messages, and releases any system resources used for message operations. 


NOTE 


It is generally good practice for a program to issue a Remove 
Receiver call immediately before issuing a Declare Receiver 
call. This prevents errors on the Declare Receiver call caused 
by abnormal termination of a previous program running under 
the same job number. 


3.4 Get Local Node Parameters Call 


The Get Local Node Parameters call returns information to the calling pro- 
gram concerning the local node. This information consists of the node name, 
address, and alias (if any), and the node’s default project-programmer num- 
ber (if any). (See the DECnet/E System Manager’s Guide for a discussion of 
alias.) 
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A general-purpose network program — one that runs on several different 
nodes rather than being specific to any one node — would use this call to 
obtain the node name, number, and alias for use in the connection sequence. 
The program uses this information to identify itself to the remote node and 
program. A program that is started automatically as the result of an incoming 
connect request would use this call to obtain the default project-programmer 
number for use in validating the connection and logging into a user account. 
(See Section 4.1.4 for a discussion of the default account.) 


3.5 Log User Event Call 


The Log User Event system call permits a user-written program to queue an 
event to the system event processor for logging. Before the event is logged, it is 
time-stamped by the system, in the standard Network Information and Con- 
trol Exchange (NICE) protocol. 


Optional parameter data can be passed to the event processor for processing 
and output. If it is included, this data must be in NICE protocol format. (See 
the DIGITAL Network Architecture, Network Management Functional Spe- 
cification, Version 3.0.0, for further information on event logging.) 


NOTE 


This system call performs a highly specialized function which 
requires a great deal of special knowledge of DECnet and the 
DIGITAL Network Architecture. It is provided as a conven- 
ience for the sophisticated network user and is not intended for 
normal network programs. 


3.6 Send/Receive Local Data Message 


The Send Local Data Message call transfers up to 532 bytes of user message 
data to a local program. The message is placed in the appropriate receive 
queue of the target program. The target program can be identified either by 
job number or by the name given in its Declare Receiver call. 


A Receive call that returns a Local Data Message returns control information 
identifying it as a Local Data Message from a specific local sender, and up to 
532 bytes of user data. 


The Local Data Message is not used for DECnet communication but is in- 
cluded here for reference. A user program can carry on local conversations and 
maintain one or more DECnet logical links at the same time. 


3.7 Send/Receive Connect Initiate Message 
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The Send Connect Initiate Message call is used to request a logical link 
connection with a remote program. 
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The target node and program are identified by a 120-byte Connect Data Block 
passed as part of the call. The following information is specified with the call: 


The user link address (ULA) that the source program will use to refer to 
this link. 


The type of receiver flow control desired by this program — that is, the 
type of flow control to be imposed on incoming data messages. (See Chap- 
ter 4 for a full discussion of flow control.) 


A receive maximum. The maximum amount of data to be received by the 
program over this link in one Network Data Message. The size of the 
receive buffers allocated by NSP will also limit the amount of data that 
can be passed in a single Network Data Message. If the maximum buffer 
size set by Network Management for NSP is not large enough to handle 
the receive maximum as specified by the user program, NSP will alter the 
receive maximum to the smaller limit before forwarding the Connect Initi- 
ate Message. The local program is informed of this change (if any is made) 
by a field in the Connect Confirm Message from the remote program when 
it accepts the link. 


A Connect Data Block identifying the target node and program to which 
the connection is requested. The target program can be identified by name 
or object type code. NSP inserts the local program identification, as speci- 
fied in the source program’s Declare Receiver call, into the Connect Data 
Block. This allows the remote program to determine who sent the connect 
request and decide whether to accept or reject the connection. The Con- 
nect Data Block can also contain data required by the remote program or 
system for access control. Such data might consist of a project-program- 
mer number, password, and account number — or whatever is required by 
the remote program or system. 


Up to 16 bytes of user data. 


A Receive call that returns a Connect Initiate Message from the queue of 
pending messages returns control information identifying it as a Connect 
Initiate Message from a specific network program, and requirements imposed 
by the remote program. The information includes the following: 


The local link address (LLA) assigned by the local NSP to refer to this 
logical link. The program will use the LLA to refer to the link in its 
responding Connect Confirm or Connect Reject Message. (Note that the 
LLA is only used to refer to a link while no user link address (ULA) is in 
effect. The ULA is established by the receiving program in its Connect 
Confirm Message that accepts the connect request and is used thereafter 
by the program to refer to the link.) 


The type of receive flow control desired by the remote program — that is, 
the type of flow control that will be imposed on outgoing data messages 
over this link. 
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A receive maximum. The maximum amount of user data that can be 
received by the local program over the link. This maximum is calculated 
by the local NSP, based on the size of receive buffers it allocates. The 
program can reduce this maximum further in its responding Connect Con- 
firm Message. 


A transmit maximum. The maximum amount of user data that can be 
transmitted by the program over this logical link in one Network Data 
Message. This maximum is imposed by either the remote NSP or the 
remote program and corresponds to the remote program’s receive maxi- 
mum. 


A 120-byte Connect Data Block, identifying the remote node and program 
requesting the link. The Connect Data Block also indicates how the re- 
mote program addressed this one (by name or object type code). If the 
program requires access control information from the remote program, 
such information would also be included as part of the Connect Data 
Block. The Connect Data Block and up to 16 bytes of user data are deliv- 
ered to the user buffer specified in the Receive call. 


3.8 Send/Receive Connect Confirm Message 
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The Send Connect Confirm Message call is used to accept a logical link 
requested by a remote program. That is, it is a positive response to a received 
Connect Initiate Message. The following information is specified with the call: 


The user link address (ULA) by which the program will hereafter refer to 
this link. 


The local link address (LLA) that identifies the link being accepted. (The 
LLA is taken from the Connect Initiate Message received for this particu- 
lar link.) 


The type of receive flow control desired by the calling program for incom- 
ing data messages over this link. (Flow control options are discussed in 
detail in Chapter 4.) 


A receive maximum. The maximum amount of user data that the program 
wishes to receive as a unit (that is, as one Network Data Message). 


Up to 16 bytes of user data. 


A Receive call that returns a Connect Confirm Message from the pending 
message queue returns control information identifying it as such, along with 
requirements for messages to be transmitted over the link. The information 
includes the following: 


The user link address (ULA) established by the receiving program in the 
Connect Initiate Message that requested the link. This identifies the par- 
ticular link being confirmed. 


The type of receive flow control requested by the remote program — that 
is, the type of flow control imposed on outgoing data messages. (Flow 
control options are discussed in detail in Chapter 4.) 
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A receive maximum. The maximum amount of user data that the local 
program will receive on this link in one Network Data Message. This will 
be the same or less than the size requested in the program’s Connect 
Initiate Message. A smaller size is indicated by the local NSP if it cannot 
handle the size requested in the Connect Initiate Message. 


A transmit maximum. The maximum amount of data the local program 
can send to the remote program as a unit (with one Network Data Mes- 
sage) over this link. 


Up to 16 bytes of user data, delivered to the user buffer specified in the 
Receive call. 


3.9 Send/Receive Connect Reject Message 


A Send Connect Reject Message call is used to reject a logical link requested 
by a remote program. That is, it is a negative response to a received Connect 
Initiate Message. The following information is specified with the call: 


The local link address (LLA) assigned by the local NSP to identify the 
link being rejected. (The local link address is taken from the received 
Connect Initiate Message.) 


A code identifying the reason for the rejection. Ordinarily, this code is zero 
unless the program is rejecting the connection due to some standard rea- 
son, such as “invalid accounting data’. 


Up to 16 bytes of user data. 


A Receive call that returns a Connect Reject Message from the queue returns 
control information identifying it as such and the following information: 


A user link address identifying the link being rejected. This user link 
address will be the same as that established by the local program in the 
Connect Initiate Message that requested the link. The link could have 
been rejected by either the remote NSP or the remote program. 


A code identifying the reason for the rejection if the link was rejected by 
the remote NSP or by the remote program for some standard reason, such 
as “invalid accounting data.” (A list of NSP rejection codes is found in 
Appendix B.) 


Up to 16 bytes of user data, if the link was rejected by the remote program 
for some nonstandard reason. This data will be delivered to the user buffer 
specified in the Receive call. 


3.10 Send/Receive Network Data Message 


The Send Network Data Message call transmits user information to a remote 
program over an established logical link. The logical link is identified by the 
user link address (ULA) established by the calling program in its Connect 
Initiate or Connect Confirm Message. The amount of user data that can be 
sent is limited to the transmit maximum established by the remote program 
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(see the previous discussion of a received Connect Initiate or Connect Confirm 
Message). Sending a Network Data Message is subject to flow control im- 
posed by the system and by the remote program, as indicated by the flow 
control option selected by the remote program. A program can request that 
link status information be returned by a Send Network Data call and use the 
information returned to schedule subsequent send and receive requests. A full 
discussion of flow control is deferred to Chapter 4. 


A Receive call that returns a Network Data Message returns identifying con- 
trol information and delivers the user data to a buffer specified in the call. 
The amount of user data received in one Network Data Message will not 
exceed the receive maximum established by this program for the logical link 
(see the previous discussion of a sent Connect Initiate or Connect Confirm 
Message). Incoming Network Data Messages are subject to system flow con- 
trol and to the flow control option, if any, requested by the local program in its 
Connect Initiate or Connect Confirm Message. If the program requests flow 
control, it must send Link Service Messages to request data from the remote 
program (see Chapter 4). 


3.11 Send/Receive Interrupt Message 


The Send Interrupt Message call is used to transmit high-priority data to a 
remote program over an established logical link. All DECnet systems main- 
tain separate data streams for Interrupt and Data Messages. The Interrupt 
Message will be delivered to the remote program ahead of all Data Messages 
waiting to be processed at the remote end. Up to 16 bytes of user data can be 
sent in an Interrupt Message. Sending an Interrupt Message is subject to flow 
control imposed by the remote system or program. The local program can 
request that link status information be returned following a Send Interrupt 
Message call and use the information returned to schedule subsequent send 
and receive requests. A full discussion of flow control is given in Chapter 4. 


A Receive call that returns an Interrupt Message returns identifying control 
information and delivers up to 16 bytes of user data to a buffer specified in the 
call. The Interrupt Message will have been queued at the head of the pending 
message queue, behind the first Data Message and behind any other pending 
Interrupt Messages queued for the program. Incoming Interrupt Messages are 
subject to flow control imposed by the local NSP. After receiving each Inter- 
rupt Message, the local program must send a Link Service Message to reen- 
able incoming Interrupt Messages from the remote program over a logical link 
(see Chapter 4). 


3.12 Send/Receive Link Service Message 
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The Send Link Service Message call is used to request data over a logical link 
— either to request data from a remote program over a flow controlled link, or 
to reenable incoming Interrupt Messages from the remote program. In these 
two cases, detailed link status information can be returned or the call can be 
issued solely to obtain this information. 
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A Link Service Message is returned on a Receive call when a link becomes 
unblocked. If a local program has tried to send a Network Data or Interrupt 
Message and failed because the remote system or program has inhibited flow, 
the local NSP informs the local program when the condition clears. To en- 
courage efficient processing of pending messages, NSP returns a Link Service 
Message on a Receive call only when the pending message queue is empty. 
Detailed link status information is returned that the local program can use in 
regulating its send and receive requests. (The format of the status information 
for a received Link Service Message is the same as that returned, upon re- 
quest, for a Send Network Data, Interrupt, or Link Service call.) 


For a more complete understanding of the uses of Link Service Messages, see 
the discussion of flow control in Chapter 4. 


3.13 Send/Receive Disconnect Message 


The Send Disconnect Message call is used to break an established logical link 
provided that all Network Data, Interrupt, and Link Service Messages previ- 
ously sent over the link have been acknowledged by the remote NSP. If they 
have not been acknowledged, the call will terminate with an error and the link 
will not be broken. Successful completion of the call means that no more 
messages can be sent over the link. The user link address is freed and can be 
used to establish another logical link. However, messages already in the pend- 
ing message queue will remain. They can (and should) be cleared from the 
queue by doing selective Receive calls using the user link address of the 
disconnected link. Once the link has been disconnected, new messages 
received for the link will be discarded by NSP. The Disconnect Message is 
sent to the remote system. When it is received by the remote NSP, the link is 
broken at that end. Up to 16 bytes of user data can be sent with a Disconnect 
Message. 


A Receive call that returns a Disconnect Message from the pending message 
queue returns control information identifying it as such, as well as a user link 
address and up to 16 bytes of user data. Receipt of a Disconnect Message 
indicates that the remote program has terminated the logical link. Further- 
more, it indicates that all previous Network Data Messages, Interrupt Mes- 
sages, and Link Service Messages sent by the remote program were placed in 
the pending message queue by the local NSP before the Disconnect Message 
was received. Once the Disconnect Message is received by the local NSP, the 
local program cannot send any more messages over the link. 


The Disconnect Message is useful in “master-slave” communication when the 
master program only transmits data and the slave program only receives data. 
Since there is no two-way communication, the master program can issue a 
Disconnect Message to break the link with the assurance that the remote 
system has received all the data sent and queued it for the slave program. 
Successfully completing the disconnect does not guarantee that the slave has 
processed the data, however. Where such guarantees are desirable, or where 
two-way communication is desired, programs should agree to terminate the 
logical link by exchanging Network Data Messages, Interrupt Messages, or 
whatever. 
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A Send Link Abort Message is used to break a logical link immediately. 
Unlike a disconnect, no attempt is made to ensure that messages previously 
sent over the link have been acknowledged by the remote system. In fact, NSP 
discards any messages it has queued for transmission for the link. (Section 
4.2.1 describes NSP transmit queuing.) No further data can be sent over this 
logical link. Received messages already in the pending message queue will 
remain but new messages received after the Link Abort Message is issued will 
not be queued for the link. Messages already in the queue can (and should) be 
cleared by doing selective Receive calls using the user link address of the 
aborted link. 


If the link is established, the Link Abort Message is sent to the remote system 
as notification that the link is broken and up to 16 bytes of user data can 
accompany the Link Abort Message. A Link Abort Message can also be sent 
for a logical link that has not yet been confirmed by the remote program. In 
this case, NSP breaks the link at the local node, but it does not notify the 
remote system. (Hence, the user data does not reach the remote program.) 
Should the remote program confirm the link, the local NSP no longer knows 
the link and it so informs the remote NSP, which notifies the remote program. 
Should the remote program reject the link, the local NSP informs the remote 
NSP that it has no such link but since the remote program rejected the link 
anyway, no notification is given to the remote program. 


A Receive call that returns a Link Abort Message from the pending message 
queue returns control information identifying it as such, as well as a user link 
address and a local link address to identify the link aborted. The local link 
address identifies a link aborted during the initial connection sequence. For 
example, if the local NSP received a Connect Initiate Message, but the local 
program has not yet responded with a Connect Confirm or Connect Reject 
Message, a Link Abort Message is queued with the same local link address as 
was specified in the received Connect Initiate Message. The link could have 
been aborted by the remote NSP or the remote program. If the link was 
aborted by the remote NSP, the message will contain a reason code identify- 
ing the reason for the rejection. If the link was aborted by the remote program, 
up to 16 bytes of user data can also be delivered with the Link Abort Message. 
Once the local NSP receives the Link Abort Message, the local program 
cannot send any more messages over the link. 
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Chapter 4 
Network Addressing and Flow Control 


With the background given in Chapters 2 and 3, we can now discuss two areas 
of interprogram communication in a DECnet network: network addressing 
and flow control. Network addressing concerns the methods whereby a pro- 
gram declares its identity for the purpose of receiving network messages. Flow 
control involves the various techniques used by DECnet to ensure an orderly 
transfer of message and control data between nodes in a network. 


4.1 Network Addressing 


When a program declares its intent to use the network message services, it is 
influenced by the following DECnet/E features: 


e The options available in the Declare Receiver call 


¢ The way in which DECnet/E NSP handles incoming requests for logical link 
connections 


e The multiple copy execution feature, by which more than one copy of a 
network program can be executed in the RSTS/E timesharing environment 


¢ The automatic job startup feature, by which DECnet/E allows programs to 
be defined by the system manager for automatic startup on receiving a 
request for a logical link connection 


4.1.1 Declaring Network Names and Object Type Codes 


Every DECnet/E program that wishes to receive messages from local senders 
or establish logical links for data exchange with other network programs must 
declare its identity in a Declare Receiver call. The program can declare its 
identity with a nonzero object type and with a null name — abbreviated to 
DR(n,null) in this chapter — with a zero object type and a nonnull name — 
DR(0,name) — or with a nonzero object type code and a nonnull name — 
DR(n,name). Remember from the discussion in Chapter 3 that nonzero object 
type codes should be used consistently throughout the network. 
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Declaring identity by object type code alone — DR(n,null) — permits multi- 
ple copies of a program to be executed without the necessity of generating a 
unique identity for each copy. DECnet/E allows more than one program to 
run and declare identity with the same object type code. Thus, several copies 
of a program can be executed simultaneously in response to incoming connect 
requests. 


On the other hand, declaring identity by name alone — DR(0,name) — re- 
quires uniqueness in the sense that no other program at the local node can 
declare identity with the same name at the same time. If a program declares 
its identity with the same name each time it runs, multiple copies cannot 
execute simultaneously. 

It is possible, however, to combine the features of uniqueness and of multiple 
copy execution. By appending the RSTS/E job number to a common root, a 
program can create a unique, nonnull name — for example, FAL21, FALOS. 
(The RSTS/E job number can be determined with the Return Job Status 
system call, described in the RSTS/E Programming Manual.) The program 
can then declare its identity with both the name created and a nonzero object 
type code. This permits multiple copies of the program to be run as a result of 
incoming connect requests but permits each copy to create its own unique 
identity. 


4.1.2 Handling of Incoming Connect Requests 


When a Connect Initiate Message is received at the local node, NSP searches 
its list of Receiver ID Blocks for the proper receiver. (All other incoming 
messages reference an established logical link and will be queued to the cor- 
rect program without searching the list of Receiver ID Blocks.) The method of 
addressing specified in the Connect Initiate Message determines how NSP 
processes the request. 

Incoming requests for logical link connections can be addressed to either an 
object type code alone — CI(n,null) — or to a name alone — CI(0,name). 
DECnet/E does not allow incoming connect requests to be addressed using 
both object type code and name. It will reject such requests, sending back a 
Connect Reject Message with a reason code indicating that the requested 
program cannot be found. 


Incoming Connect Request Addressed to Object Type Code — Ci(n,null) 


If the incoming Connect Initiate Message is addressed to an object type code 
— ClI(n,null) — NSP checks its Receiver ID Blocks to see if one or more 
programs are running that have declared identity with this object type code. 
The Declare Receiver call could have specified either DR(n,null) or 
DR(n,name). 

If one or more such receivers are found that have not reached their declared 


logical link maximum or message maximum, NSP queues the connect request 
for the first such receiver in its list (ordered by job number). 


NOTE 


Remember from Chapter 3 that a program sets its own limits 
on the number of logical links allowed and the size of the pend- 
ing message queue in the Declare Receiver call. 
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If there is no such receiver or if there are one or more such receivers but all 
have reached their declared logical link maximum or message maximum, 
NSP attempts to start another copy of the program. This process is described 
fully in Section 4.1.4 and also in the DECnet/E System Manager’s Guide. 
Briefly, NSP checks to see if the program identified in the Connect Initiate 
Message has been defined by the system manager for automatic startup. If so, 
NSP creates a job and starts the program. The program must then issue a 
Declare Receiver call with the appropriate object type code. This creates a 
Receiver ID Block and a pending message queue to which the waiting Connect 
Initiate Message can then be transferred. If the program does not issue a 
Declare Receiver call within two minutes, NSP rejects the link by returning a 
Connect Reject Message to the remote program. 


Incoming Connect Request Addressed to Name — Ci(0,name) 


When the incoming Connect Initiate Message is addressed to a name — 
CI(0,name) — NSP checks its list of Receiver ID Blocks to see if a program is 
running that declared its identity with this name. The Declare Receiver call 
could have specified either DR(0,name) or DR(n,name). 


If such a receiver program is running, and it has not yet reached its declared 
logical link maximum or message maximum, the Connect Initiate Message is 
placed in the receiver’s queue of pending messages. 


If no such program is running, NSP will attempt to start the program. If it is 
successful in doing so, the program started must declare its identity with the 
appropriate name. Again, if the program fails to issue a Declare Receiver call 
within two minutes, NSP rejects the connection. 


If such a program is running, but it has reached its declared logical link 
maximum or message maximum, NSP rejects the connection, returning a 
Connect Reject Message with an appropriate reason code explaining the rejec- 
tion. Automatic startup is not attempted in this case, because a program is 
already running with the name to which the Connect Initiate Message was 
addressed. A second copy with the same name cannot be generated since 
receiver names must be unique. 


4.1.3 Multiple Copies 


In a DECnet/E system, multiple copies of a program can be started by a local 
terminal user, through the RSTS/E BATCH processor, or through the auto- 
matic job startup feature. The manner in which copies of a program can be 
started has some bearing on the way in which a Declare Receiver call should 
be issued. 


Multiple Copies Initiated by Terminal Users 


A program run from a local terminal with the purpose of communicating with 
a remote program will normally send at least the initial Connect Initiate 
Message requesting a logical link. (It is unlikely that remote users would wish 
to have the success of incoming link connections rely upon someone starting 
the program manually.) 
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In this case, the program can declare its identity with DR(n,null), or with 
DR(n,name) or DR(0,name) as long as the program generates a unique name 
with each copy, as described in Section 4.1.1. The choice depends on whether 
or not the program receives any connect requests, and if so, if it is necessary 
for the remote program to connect with a specific copy. 


Suppose, for example, that the local program issues the initial Connect Initi- 
ate Message for establishing the first logical link. Suppose further that it is 
then necessary for the remote program to establish a second logical link with 
the same copy that sent the Connect Initiate Message for the first link. The 
local program can declare its identity with either the form DR(0,name) or 
DR(n,name). The unique copy name is passed to the remote program in the 
Connect Data Block in the Connect Initiate Message. The remote program 
can then address its connect request in the form CI(0,name) to ensure that the 
request is delivered to the same copy that issued the first Connect Initiate 
Message. 


Multiple Copies Executed under BATCH 


Multiple copies of a program can also be executed through use of the RSTS/E 
BATCH processor (see the RSTS/E System User’s Guide). Again, such pro- 
grams will normally be responsible for initiating at least the first logical link 
connection. The techniques described previously for multiple copies started 
by terminal users would also apply here. 


Multiple Copies Initiated through Automatic Startup 


Multiple copies of a program can also be initiated for programs that the 
system manager has designated for automatic job startup. Such copies result 
from incoming connection requests addressed CI(n,null). (See Section 4.1.4 
for full details.) The local program can declare its identity with DR(n,null), or 
with DR(n,name) as long as the name is unique for each copy. 


4.1.4 Automatic Job Startup 


Using the Network Control Program (NCP), the system manager can install 
user programs for automatic startup. Such programs reside as files on disk in 
the normal fashion and can be started by NSP to fulfill incoming requests for 
logical link connections (see Section 4.1.2). This installation method is de- 
scribed fully in the DECnet/E System Manager’s Guide. Briefly, a DEFINE 
OBJECT or SET OBJECT command in NCP relates the file name to, again, 
an object type code, a name, or both. These commands also allow two param- 
eters to be associated with a program. For BASIC programs, the first parame- 
ter is used as a starting line number. The second parameter is made available 
to the program when it is automatically started. 


NSP maintains a list of these definitions in its parameter file. The definitions 
are ordered by object type code, and thus, there can be only one program 
defined for automatic startup for each object type code. In particular, there 
can be only one program defined for automatic startup with an object type 
code of zero — (0,name). The same program can, however, be defined more 
than once, with different names, object type codes, starting line numbers, and 
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parameters. In other words, it is possible to design a program with different 
entry points when it is addressed by different names or object type codes in 
the incoming connect requests. 


When a program must be started automatically, NSP checks the object type 
code or name given in the incoming connect request against its list of defined 
programs. If a match is found, NSP executes a monitor request to run the 
program as a detached job under RSTS/E. 


Once started, the program must declare its identity with the object type code 
or name that was specified in the Connect Initiate Message that caused the 
program to be started. If it does not, the connect request will never be deliv- 
ered to the proper pending message queue. 


NSP passes this information to the started program in core common. Any 
optional parameter established by the DEFINE OBJECT or SET OBJECT 
command is also passed in the string. A BASIC program can retrieve the core 
common data by issuing the Get Core Common String system call (SYS call 
7), as described in the RSTS/E Programming Manual. The format of the core 
common string is as follows: 


Byte(s) Contents 

CORCMN+0 Length of data in core common 

+1 Object type code (0-255) 

+2-7 Name (ASCII) 

+8-9 Second DEFINE parameter (-32768 through 32767) 
+10 Reserved 


The mnemonic CORCMN is assigned by the file COMMON.MAC to octal 
location 460 (see the RSTS/E System Directives Manual). 


If the object type code in byte 1 of core common is nonzero, the program must 
declare its identity with that object type code. It can also use a nonnull 
unique name, if desired. If the object type code is zero, the program must 
declare its identity with the name given in bytes 2-7 of core common. It can 
also declare its identity with a nonzero object type, if desired. 


When the Declare Receiver call is issued, NSP transfers the waiting connect 
request to the program’s queue of pending messages as a Connect Initiate 
Message. NSP waits two minutes from the time it starts the program for the 
connect request to be transferred. 


If the connect request is not transferred to a queue within this time period, 
NSP rejects the connection, sending a Connect Reject Message to the remote 
program. Since the remote program could also abort the link within this 
period, the first action of an automatically started program (after issuing the 
Declare Receiver call) should be to issue a Receive call to check for pending 
messages. If there are none, the program should issue a Remove Receiver call, 
and terminate execution with the Kill Job system call. (See the RSTS/E 
Programming Manual.) Once the connect request has been received, the pro- 
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gram should respond to the request immediately. While the local NSP’s timer 
is stopped when the message is transferred to the receiver’s pending message 
queue, the remote node could be executing a timeout on the Connect Initiate 
Message. 


A program that has been started in response to an incoming Connect Initiate 
Message runs as a privileged RSTS/E user, and it is the responsibility of that 
program to protect the rest of the system from unauthorized outside access. 
Thus, after receiving the Connect Initiate Message, the program should check 
the accounting information passed in the Connect Data Block to determine 
the user account (and, therefore, the privilege level) in which it should run. If 
no such information is specified in the Connect Data Block, the program 
should issue a Get Local Node Parameters call to obtain the local node’s 
default project-programmer number, if any. If a default account has been 
specified, the program should then look up the password for that account 
using the Read Accounting Data system call and log into the default account. 
(See the RSTS/E Programming Manual.) If the local node has no default 
account, the connect request should be rejected. (Programs that always log 
into a predetermined account need not go through this procedure.) 


4.1.5 Examples of Network Addressing 


This section presents three examples of network addressing using the features 
just discussed. 


The first example (Figure 4-1) shows the network addressing used by two 
DECnet/E utility routines — the Network File Transfer utility (NFT) and the 
File Access Listener (FAL). NFT is run by local users to connect with a 
remote FAL to access files at remote nodes. FAL is run at the local node as 
result of incoming connect requests from a remote NFT. Both programs are 
designed to execute multiple copies as demand requires. 


Since NFT is started only by local terminal users and never by remote re- 
quest, an object type code is not necessary. NFT is loaded from the system 
disk and declares its identity with an object type code of zero and a unique 
name each time it is run. NFT issues the Connect Initiate Message to estab- 
lish a logical link for the transfer of data to or from remote nodes as specified 
by the user. 


Copies of FAL are started by incoming Connect Initiate Messages addressed 
to object type code 17. FAL declares its identity with object type code 17 and 
a unique name. It also declares that the maximum number of logical links 
allowed is one so each incoming connect request starts a new copy. 


The second example (Figure 4-2) shows NETCPY, a device copying program 
that can be started either by local terminal users or by incoming connect 
requests. The program copies an entire device between nodes. Multiple copies 


Network Programming in BASIC-PLUS and BASIC-PLUS-2 





LOCAL NODE 








CONNECT INITIATE 





REMOTE 
NODE 









CONNECT INITIATE 


CONNECT INITIATE 


REMOTE 
NODE 
CONNECT INITIATE 


RUN SNFT 


Figure 4-1: Network Addressing Used by NFT and FAL 


are executed according to demand. Here, the Declare Receiver call is different 
depending on how the program is started. NETCPY is a BASIC-PLUS pro- 
gram and takes advantage of the starting line number feature. Using the 
Network Command Program (NCP), the system manager issues a command 
to SET or DEFINE NETCPY.BAC as object 20, with a starting line number 
of 29000. If NETCPY is started by a Connect Initiate Message from a remote 
program addressed to object type code 20, the program declares its identity 
with object type code 20, a unique name, and a link maximum of one. If it is 
started by a local terminal user, it declares its identity with an object type 
code of 0, a unique name, and a link maximum of zero. Declaring a zero link 
maximum ensures that a program started by a local user will never have a 
Connect Initiate Message queued from a remote program. 


The third example (Figure 4-3) shows a program that can be run either by a 
local terminal user or as a result of an incoming connect request. The local 
terminal user is presented with a data display. Parameters are selected by the 
user and passed to a remote program monitoring a data gathering device. At 
the end of the day, the remote program passes the data back to the local 
program for analysis and to the local terminal user, who repeats the process. 
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Figure 4-2: Network Addressing Example — Different Declare Receiver 
for Local and Remote Start 


Since only one copy of the program is ever needed at any given time, it 
declares its identity with a zero object type code and the name STAT. It is 
stored as file RSTAT.SAV on disk, where it can be run by the local user. 
Using NCP, the system manager has issued a command to SET or DEFINE 
RSTAT.SAV as STAT. 


4.2 Flow Control 


DECnet flow control protects user programs as well as entire systems from 
being flooded with more messages than can be processed at any given time. 


A DECnet/E sender is subject to flow control regulations imposed by the local 
NSP, the remote NSP, and the remote program (if the remote program re- 
quested flow control when the link was established). As a receiver, a DEC- 
net/E program can select from three flow control options for a logical link to 
regulate the amount of data sent to it by the remote program. 


As a sender and/or receiver, a program must deal with the following four 
aspects of DECnet/E operation: 


¢ Transmit queue management, imposed by the local (sending) NSP, en- 
sures that a local program does not use too much system buffer space for 
transmission. 


¢ Backpressure flow control, imposed by the remote NSP, is used as a 
safeguard against excessive incoming data messages. 
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Figure 4-3: Network Addressing Example — Declaring Identity by 
Name Alone 


¢ Data message flow control, imposed by receiving user programs, enables a 
program to control the flow of data to it. Both programs using a logical link 
can (independently) choose to receive network messages only when they 
specifically request data from the other program; or each can choose no flow 
control, placing no restrictions on the amount of data that they will receive. 


interrupt message flow control, imposed by either the remote NSP or the 
remote program (depending on the DECnet implementation), protects 
against Interrupt Message congestion. A DECnet/E program can receive 
only one unsolicited Interrupt Message over a link. After that, the program 
must request an Interrupt Message before the remote program can send one. 


4.2.1 Transmit Queue Management 


Once a logical link is established, DECnet/E maintains two transmit queues 
for the link: a transmit queue for Network Data Messages and a transmit 
queue for Interrupt and Link Service Messages. Both queues hold messages 
waiting for acknowledgment from the remote NSP. 


For example, when a DECnet/E program sends a Network Data Message to a 
remote program over a logical link, the message is queued to the Transport 
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software for transmission and is also placed in the data transmit queue. The 
Network Data Message is held there until the local NSP receives an acknowl- 
edgment from the remote NSP indicating that it has received the message. 


If NSP does not receive an acknowledgment within a reasonable period of 
time, it assumes that the message has been lost and requeues it to Transport 
for retransmission. If the message has not been successfully transmitted after 
a specific number of retries, NSP aborts the link with a reason code indicating 
that the remote system is not responding. 


The timeout period used depends on the message type. For outgoing Connect 
Initiate Messages, a predetermined value is used. Once a logical link is estab- 
lished, however, network management dynamically computes the timeout 
period, using various network parameters defined by the system manager 
using NCP and the SET EXECUTOR command. (See the DECnet/E System 
Manager’s Guide for details.) 


This acknowledgment procedure between the two NSPs ensures that mes- 
sages sent over the logical link have been received, and that they were 
received in the same order they were sent. 


Each of the transmit queues for a logical link can hold up to eight messages. 
(This limit can be changed by the system manager to any number from one to 
eight to further protect system buffer space.) When one of the transmit queues 
for a logical link is filled with messages waiting for acknowledgment, further 
transmission of that type of message over the logical link is inhibited by the 
local NSP until one or more of the queued messages have been acknowledged 
by the remote NSP. 


An error is returned to the program if it issues a send request while the 
transmit queue for that message type is full. This condition is temporary. 
When the condition clears, send requests are again allowed for that message 
type. A program getting such an error on a send request should simply wait a 
short time (1 to 5 seconds) and retry the send request. 


The state of the transmit queues also affects the sending of Disconnect Mes- 
sages. If any messages are waiting for acknowledgment in the Data or Inter- 
rupt/Link Service transmit queue, a Send Disconnect Message call for that 
logical link will not be allowed and will result in an error. Thus, a program 
sending a successful Disconnect Message can assume that all previously sent 
messages have been received and acknowledged by the remote NSP. A Link 
Abort Message for that logical link will be allowed, however, and any mes- 
sages waiting in the transmit queues will be discarded. 


Figure 4-4 illustrates transmit queue flow control. PROGA has established 
two logical links, and PROGB and PROGC have each established one logical 
link. Each logical link has its own Data and Interrupt/Link Service Message 
transmit queues. PROGA issues a Send Network Data Message system call. 
The message goes to the Data transmit queue for that logical link and is also 
queued for transmission by the communication hardware. At the device driver 
level, all network messages (both data and control messages) await transmis- 
sion over the physical line. 


PROGB is shown trying to send a Network Interrupt Message. The Inter- 
rupt/Link Service transmit queue for that link is full, however, so NSP returns 
an error on the send. PROGC issues a Disconnect Message for its logical link. 
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Since messages are still waiting for acknowledgment in the transmit queues, 
the Disconnect Message is not allowed and an error is returned. (Sending a 
Link Abort Message would have broken the link but the messages would have 
been discarded.) 


LOCAL NODE 



















USER 
PROGRAM 


REMOTE 
NODE 


INT./L.S. 
XMIT 
QUEUE 


ERROR - UNACKNOWLEGED 
MESSAGES STILL IN 
TRANSMIT QUEUES 





Figure 4-4: How Transmit Queue Flow Control Affects 
a DECnet/E Program 
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4.2.2 Backpressure Flow Control 


NSP at the remote node can inhibit the local program from sending Network 
Data Messages over a logical link. The reasons for this blocking can vary from 
system to system: lack of system buffer space, system load, or some similar 
condition. This type of flow control, whereby the remote NSP can inhibit 
message flow from the local program, is known as backpressure. 


When the remote NSP receives a Network Data Message that it cannot pro- 
cess, it returns a negative acknowledgment (NAK) for the message, along with 
an error code informing the local NSP that data message flow to the remote 
program is being inhibited on the link over which the message was sent. The 
local NSP then inhibits transmission of Network Data Messages over the 
indicated logical link until further notice is received from the remote NSP. 
(Note that the local program can still receive messages over the logical link.) 
When the remote NSP informs the local NSP that the backpressure condition 
has cleared, the local NSP retransmits the message that was previously- 
NAKed and reenables transmission of Network Data Messages over the logi- 
cal link. 


If the backpressure condition clears before the local program attempts another 
send over the link, the program is not informed that the conditon occurred. 
However, if the program attempts to send another Network Data Message 
while transmission on the link is still inhibited, the local NSP returns an error 
to the program (see A, in Figure 4-5). When the condition clears, the local 
NSP delivers a Link Service Message to the program, informing it that trans- 
mission of Network Data Messages is again allowed for the indicated logical 
link (see B, in Figure 4-5). This Link Service Message is delivered to the local 
program on a Receive call when the queue of pending messages is empty. 


Note that the remote NSP enforces flow control for specific logical links, not 
for the entire node. 


From the reverse viewpoint, the local NSP will inhibit incoming data mes- 
sages over a logical link when a Network Data Message is received from a 
remote program over the link and the pending message queue of the intended 
receiver is full. (Remember that the local program itself limits the size of its 
pending message queue in its Declare Receiver call.) The local NSP informs 
the remote NSP that incoming data message flow has been inhibited by 
sending a message to the remote system. 


Under these conditions, the Network Data Message is not queued for the local 
program, but is NAKed by the local NSP. This forces the remote NSP to 
retransmit the message after flow is reenabled. Any data messages already 
transmitted by the remote node will also be NAKed by the local NSP. 


Furthermore, the local NSP marks all other logical links on the Receiver ID 
Block to be turned off if any Network Data Messages are received on those 
links. However, no message is sent to the remote system unless a Network 
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Data Message is received on one of these links before the restriction is lifted. 
(Note that while the local NSP will no longer accept incoming messages, the 
local program can still transmit.) 


When the local program empties its pending message queue, any links that 
were actually turned off are turned back on and a message is sent to the 
remote NSP to reenable transmission. Those links that were merely flagged to 
be turned off are restored to normal operation, but no message is sent to the 
remote system. 


A. Remote node backpressures a link off 
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LINK X OFF 


REMOTE 
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we HARDWARE 
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ERROR - LINK BACKPRESSURED 
OFF 






B. Remote node clears backpressured link, local program notified on receive 


LOCAL NODE 









USER 
PROGRAM 


NODE 


HARDWARE 
XMIT 
QUEUE 











INT/L.S. 
XMIT 
QUEUE 


Figure 4-5: How Backpressure Flow Control Affects 
a DECnet/E Program as a Transmitter 
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4.2.3 Program-Regulated Flow Control 


During the connection sequence that establishes a logical link, each program 
must select one of the following three flow control options to regulate incom- 
ing data over the link: 


¢ Segment Flow Control. The program requests data from the remote pro- 
gram by indicating how many segments it will accept at any given time. A 
segment is defined as the amount of user data transferred in one Network 
Data Message. The maximum size of a segment is determined by the receive 
maximum established in the Connect Initiate or Connect Confirm Message. 
The sending program is not required to use this maximum, however, and 
can, in fact, send smaller segments. Note also that segments transmitted 
and received by the same program are not necessarily equal in size. 


¢ Logical Message Flow Control. The program requests data from the re- 
mote program by indicating how many logical messages it will accept at any 
given time. A logical message can consist of one or more data segments. 
Control flags, included as part of a Network Data Message, indicate 
whether the data segment is the beginning, middle, end, or sole segment of a 
logical message. 


¢ No Active Flow Control. The program sets no limits on the rate at which 
messages can be sent to it over a logical link. 


If the program selects segment flow control or logical message flow control, the 
remote NSP will not send Network Data Messages over the link until the local 
program requests such transmission. Requests are made by sending a Link 
Service Message requesting a specific number of segments or logical messages. 


If the program selects the third option, no active flow control, no Link Service 
Messages can be sent except those requesting Interrupt Messages. Network 
Data Messages will be transmitted by the remote NSP as the remote program 
sends them, subject to backpressure. 


Flow control selection is independent at both ends of the logical link. That is, 
the remote and local programs need not select the same type of flow control. 
The option selected by the remote program, however, affects how the local 
program can send Network Data Messages. Therefore, the following discus- 
sion of flow control is presented from two viewpoints: 


1. How the option selected by the local program affects incoming Network 
Data Messages 


2. How the option selected by the remote program affects the way the local 
program sends Network Data Messages 


Flow Control on Incoming Data 


If the local program selects logical message flow control in the Connect Initi- 
ate or Connect Confirm Message establishing a logical link, the local program 
must request data from the remote program by sending Link Service Mes- 
sages specifying the number of logical messages to be transmitted. 
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When the Send Link Service Message call is issued, the local NSP adds the 
value specified to a message counter maintained for the link. The local NSP 
also sends the information on to the remote NSP. The remote NSP likewise 
adds the value specified to a message counter it maintains for the link. Thus 
both NSPs count the outstanding message requests. Each time the remote 
NSP sends the end segment of a logical message, it decrements the message 
counter. When the counter reaches zero, the remote NSP will inhibit trans- 
mission until the local program sends another Link Service Message specify- 
ing another value to add to the message counter. 


The local NSP uses its message counter as a protective measure. Each time it 
receives a data segment with the end-of-logical-message flag set, it decre- 
ments the message counter. When the counter reaches zero, the local NSP no 
longer accepts data segments over the link. Should the remote NSP send a 
segment while the local NSP’s counter is zero, the message is discarded and 
the link is aborted. The local NSP places a Link Abort Message in the local 
program’s queue of pending messages and sends a Link Abort Message to the 
remote NSP. (This situation is a protocol violation and should not occur with 
correct NSP operation.) 


When the local program selects segment flow control in the Connect Initiate 
or Connect Confirm Message, the local and remote NSP maintain segment 
counters for the logical link. The remote program can still send segments with 
the logical message control flags set for the local program to process inter- 
nally, but the counters maintained by NSP are kept for data segments sent, 
not for logical messages. Data is requested by sending a Link Service Message 
indicating the maximum number of segments to be sent. The local and remote 
NSPs add this value to their data segment counters and then decrement the 
counters as the remote program sends segments. When the data segment 
counter reaches zero, transmission over the logical link is suspended until 
another Link Service Message increments the count. 


When no active flow control is requested in the Connect Initiate or Connect 
Confirm Message, segments from the remote program can be transmitted over 
the logical link without being requested by the local program. The local and 
remote NSPs do not keep counters to regulate data sent and Link Service calls 
are not used to request transmission of data. Data Message flow can still be 
restricted by backpressure, however. 


Flow Control on Outgoing Data 


When the remote program specifies a flow control option in its Connect Initi- 
ate or Connect Confirm Message establishing the logical link, the local NSP 
notes the option and establishes the appropriate counter. The counter is in- 
creased when a request for data is received from the remote system or pro- 
gram. If the remote program requested segment flow control, the counter is 
decremented by one each time the local program issues a Send Network Data 
Message call. If the remote program requested logical message flow control, 
the message counter is decremented by one each time a Network Data Mes- 
sage is sent that is flagged as the end data segment of a logical message. 


When the counter equals zero, the local NSP inhibits further transmission of 
Network Data Messages. over the logical link, returning an error if the local 
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program tries to do so. In this circumstance, the local NSP delivers a Link 
Service Message to the local program when the condition clears and the pend- 
ing message queue is empty. A Link Service Message is not delivered, how- 
ever, if the local program did not attempt to send a Network Data Message 
while the request count was zero. 


This process is illustrated in Figure 4-6. The remote program has requested 
segment flow control. First, the remote program requests two segments (see A, 
in Figure 4-6). The segment counter for the remote program is incremented, 
but since PROGA has not had transmission inhibited, no Link Service Mes- 
sage is queued. The local program issues three Send Network Data Message 
calls (see B, in Figure 4-6). The segment counter is decremented to one with 
the first send, and to zero with the second send. The third send, while the 
counter is zero, results in an error. When the remote program receives and 
processes its two segments, it asks for two more segments (see C, in Figure 
4-6). The segment counter is incremented from 0 to 2, reenabling data sends. 
Since PROGA attempted a send that failed, a Link Service Message is deliv- 
ered to PROGA to indicate that data flow over the link has been reenabled. 
The Link Service Message is delivered to PROGA when it executes a Receive 
call when the pending message queue is empty. 


4.2.4 Interrupt Message Flow Control 


The transmission of Interrupt Messages over a logical link is subject to flow 
control by a request count mechanism. This mechanism is controlled by either 
the remote NSP or the remote program, depending on the particular DECnet 
implementation. 


All logical links are initiated with an outstanding Interrupt Message request 
count of one from the remote system. If the local program sends an Interrupt 
Message over the logical link, this count is decremented to zero. The local 
NSP does not allow another Interrupt Message to be sent over this logical link 
until the remote NSP or remote program sends a Link Service Message, 
incrementing the request count. An attempt by the local program to send an 
Interrupt Message while the counter is zero will result in an error. 


Once the request count is incremented by the remote system or program, the 
local NSP reenables Interrupt Message flow. If the local program has tried to 
send an Interrupt Message while the count was zero, NSP notifies the local 
program with a Link Service Message that Interrupt Messages can again be 
sent over this logical link. This Link Service Message is delivered to the local 
program on a Receive call when the pending message queue is empty. If the 
local program has not tried to send an Interrupt Message over the link while 
flow was disabled, no Link Service Message is delivered. 


From the reverse viewpoint, all DECnet/E logical links are initiated with an 
outstanding request for one Interrupt Message. If the remote program sends 
an Interrupt Message over the link, the local NSP decrements this count to 
zero. No further Interrupt Messages are accepted until the local program 
requests one by sending a Link Service Message to increment the count. This 
also increments the request counter at the remote end and thus allows the 
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A. Remote program requests two segments 
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B. Local program sends two segments, third send returns an error 


LOCAL NODE 
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C. Remote program requests two segments, local program notified on receive 


LOCAL NODE 





USER 
PROGRAM 
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REMOTE 
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Figure 4-6: How the Flow Control Option Selected by the Remote 
Program Affects a DECnet/E Program as a Transmitter 
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remote program to send an Interrupt Message if it so desires. DECnet/E NSP 
does not allow the local program to request an Interrupt Message for a logical 
link unless a previous Interrupt Message on the link has been received. 


In DECnet/E, only one Interrupt Message can be requested on a logical link at 
any one time. That is, the request count is either zero or one. If a program 
tries to issue a Link Service Message requesting an Interrupt Message on a 
link when the request count is already one, the Link Service Message will 
result in an error. 


Figure 4-7 illustrates Interrupt Message flow control for a DECnet/E receiver. 
The remote program sends an Interrupt Message over a logical link (see A, in 
Figure 4-7). The local NSP decrements the Interrupt Message counter to zero 
and does not accept further Interrupt Messages over this link. The remote 
NSP also decrements its own counter and inhibits further Interrupt Messages 
from being sent. The local NSP maintains its counter as a safeguard measure. 
The local program sends a Link Service Message requesting one Interrupt 
Message over this logical link (see B, in Figure 4-7). The local NSP incre- 
ments its counter and tells the remote NSP to reenable Interrupt Messages 
over the link. The local program must receive the first Interrupt Message 
before the Link Service Message can be sent. 


4.2.5 Programming Hints for Flow Control 


A DECnet/E program can be prevented from transmitting for a number of 

reasons: 

1. No buffer space is available at the local node. (Prohibits sending of all 
message types.) 


2. The Data transmit queue is full. (Prohibits sending of Data Messages.) 


3. The Interrupt/Link Service transmit queue is full. (Prohibits sending of 
Interrupt and Link Service Messages.) 


4. Message flow over the link has been inhibited by the remote system be- 
cause of backpressure condition. (Prohibits sending of Data Messages.) 


5. No requests are outstanding for segments or logical messages from the 
remote program. (Prohibits sending of Data Messages.) 


6. No requests are outstanding for Interrupt Messages. (Prohibits sending of 
Interrupt Messages.) 


The first three conditions indicate congestion at the local node. They are 
temporary and no notification is given to the program when the condition 
clears. When one of these errors occurs on a send call, the program should 
simply reissue the call after a short delay of one to five seconds. 


The last three conditions, however, indicate congestion at the remote node. 
Since there is no way to predict how long it can take for one of these condi- 
tions to clear, the local NSP does not allow further send requests of Data or 
Interrupt Messages until the remote system indicates that the condition has 
cleared. 
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A. Remote program sends an Interrupt Message over a logical link 
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B. Local program reenables interrupts for the link (allowed only when previous Interrupt Message for this logical link has been 


received) 
LOCAL NODE 
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Figure 4-7: How Interrupt Message Flow Control Affects 
a DECnet/E Program as a Receiver 


When sending is blocked for one of these last three conditions, any attempt to 
send a message by the local program results in an error. The program can still 
receive messages, however. If an attempt to send a message resulted in an 
error in this fashion, NSP notifies the program when the condition clears. It 
does this by delivering a Link Service Message to the program when the 
program issues a Receive call and the pending message queue is empty. No 
notification is given if the local program did not try to send a message. 


Thus a program whose main function is to transmit data can be designed to 
send data over a logical link until transmission is blocked by one of the last 
three conditions. When sending is inhibited, the program can issue Receive 
calls to process all pending messages. When the pending message queue is 
empty and all conditions that block flow have cleared, a Link Service Message 
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is delivered on a Receive call, giving current status information on flow con- 
trol for the logical link. (If more than one logical link has been blocked, 
Receive calls should be issued for all links until no messages are returned, 
since link service information can also be available on the other links.) 


A program whose main function is to receive data is concerned with keeping 
the pending message queue emptied so that the queue does not fill and cause 
the local NSP to inhibit incoming message flow over the program’s logical 
links. The Receive call with sleep can be used effectively by such a program so 
that it will be notified when a message is delivered to the queue. In this case, a 
second Receive call must be issued to retrieve the message. 


An interactive program can choose between these mostly-send and mostly- 
receive approaches, according to the requirements of the application. A pro- 
gram can also take advantage of the link status information that can be 
returned after sending Network Data, Interrupt, and Link Service Messages 
to regulate send and receive requests. The link status information returned is 
in the same format as a received Link Service Message. 
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Chapter 5 


Network Programming in BASIC-PLUS 


This chapter presents the specific system calls, with detailed formats, used to 
( access the DECnet/E message services in the BASIC-PLUS programming 


language. 


5.1 Programming Background 


In BASIC-PLUS, the system calls for message services, both local and DEC- 
net, are coded as SYS calls to the RSTS/E File Processor (FIP). 


Cc 5.1.1 General Format of SYS Calls 


The general format of the message SYS calls in BASIC-PLUS is: 
v$ = SYS(CHR$(6%) + CHR$(22%) + CHR$(s%) + ...) 


where 


v$ 


CHR$(6%) 


is the name of a string that will receive control informa- 
tion returned by some of the calls — the target string. 
(The dollar sign indicates a character string variable.) 


is the assignment operator. 
indicates a system call. 


is the concatenation operator required between function, 
subfunction, and argument values. 


is the system function code for a call to the File Processor 
(FIP). (The CHR$ function converts the integer value 6 — 
the % indicates an integer in BASIC-PLUS — to the char- 
acter string format required in SYS calls.) 
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CHR$(22%) is the send/receive function code. 


CHR$(s%) is the user-specified subfunction code. (For example, s = 1 
indicates a Declare Receiver system call; s = -2 indicates a 
Send Connect Initiate Message system call.) 


indicates other arguments required for the various system 
calls. These arguments must be specified in character 
string format. The CHR$(x%) construction can be used for 
one-byte integer values. CHR$(x%) + 
CHR$(SWAP%(x%)) can be used for two-byte integers. 
ASCII values are enclosed in quotation marks. (Useful 
coding conventions for SYS calls are described in Chapter 
7 of the RSTS/E Programming Manual.) 


5.1.2 Buffer Allocation for Message Operations 


Local and DECnet communication normally requires the use of buffer areas to 
hold user data being sent to another program or to receive data from another 
program. The send calls allow the data to be sent from a buffer or appended to 
the SYS call string. Buffers are usually required to receive data. 


Opening any device on any I/O channel allocates a buffer for I/O to or from 
the device. There are twelve I/O channels available to each BASIC-PLUS 
program running under RSTS/E, referenced by the numbers 1 through 12. A 
convenient way to allocate a buffer for message operations is to open the null 
device on any channel, using the RECORDSIZE option to specify the length 
of the buffer desired. For example, 


OPEN "NL:" AS FILE 12%, RECORDSIZE 128% 


would allocate one 128-byte buffer. The null device is used because it is 
always available and can be opened as many times as necessary (up to 12) to 
obtain required buffers. Also, opening the null device does not imply any side 
effects as sometimes occurs when opening a real device. 


In the send/receive SYS calls, the buffer is referenced by the channel number 
— CHR$(12%) in the previous example. Channel 0 can also be used if 128 is 
added to the channel number: for example, CHR$(128%+0%). (This, in fact, 
works for all channel numbers: CHR$(128%+x%), for x = 0 to 12.) Data in the 
buffer can be referenced with FIELD statements or moved with standard 
LSET and RSET statements in BASIC-PLUS. 
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5.1.3 Notation Used in This Chapter 


The SYS call descriptions in this chapter are organized as separate subsec- 
tions. The heading gives the name of the call and the word “Privileged” if the 
call can be issued only from a privileged program. (“Privilege” is a special 
condition for a user job under RSTS/E, as defined in the RSTS/E Program- 
ming Manual.) “Local” or “DECnet” (or both) on the heading line indicates 
whether the call is used for local or network message services. 


The first page of each call description consists of an introductory paragraph, 
followed by a table showing the specific format of the data passed and re- 
turned for each call. The first column of the table indicates the byte position 
of each field within the string. The second column indicates the value of the 
field, and the third column gives a brief description of the way the value is 
used. Lowercase items in italics are to be supplied by the user. The following 
forms appear: 


CHR$(6%) indicates a one-byte field, in character string format, that 
must have the value shown (6 in this particular case). 

CHR$(x%) indicates a one-byte field, in character string format, with 
x being an integer constant or variable name supplied by 
the user. 

CHR$(0%) 

or 0% indicates that the integer value zero appears, in character 


string format, in all bytes of the field. Zeros must appear 
in reserved fields. It is also good practice to fill ignored 
fields with zeros. This could be coded as CHR$(0%) for 
one-byte fields or as STRINGS$(n%,0%) for n-byte fields. 


x% indicates a two-byte field, with x being an integer constant 
or variable supplied by the user. Such variables can be 
converted to character string format using the construc- 
tion CHR$(x%) + CHR$(SWAP%(x%)). 


abc$ indicates a character string value — either a constant en- 
closed in quotes, such as “STRING”, or a variable name 
that has been previously defined to contain the desired 
string value. 


The format table is followed by an expanded discussion of the user-supplied 


arguments. A description of possible errors that can occur for each call is given 
next, followed by a brief example of each call. 


Network Programming in BASIC-PLUS 5-3 


5.2 Declare Receiver — Privileged 


5-4 


(Local and DECnet) 


The Declare Receiver call must be executed before a program can receive any 
messages or send any network messages. (Local messages can be sent without 
first executing this call.) The call defines an identifying object type or name 
(or both) and any restrictions on incoming messages. The monitor associates 
this information with the RSTS/E job number, setting up a Receiver ID Block 
for the job as described in Section 3.2.3. Only one Declare Receiver call can be 
in effect at any one time for a particular job. It remains in effect until a 
Remove Receiver call is issued for the job. 


Data Passed: 


Bytes Value 

1 CHR$(6%) 

2 CHR$(22%) 

3 CHR$(1%) 

4 CHR$(0%) 

5-10 name$ 
11-12 0% 
13-16 0% 
17-20 0% 
21 CHR$(objtyp%) 
22 CHRS$(access%) 
23-24 bmax% 
25 CHR$(mmax%) 
26 CHR$(lmax%) 
27-28 0% 
29-40 0% 


Description 


SYS call to FIP. 

Send/receive function code. 
Declare Receiver subfunction code. 
Reserved - must be zero. 


Logical name: 1 to 6 characters. Left-justified with space 
fill to 6 characters. Or null if network access by object type 
only. 


Reserved - must be zero. 
Ignored. 
Reserved - must be zero. 


Object type code, 0 to 255: If + 0, this value can be used by 
remote programs to address the calling program. 


Access control field = 1% + p% + n% + 0% + s%: 


| Local senders? QO=no, 1=yes 
p Privileged local senders? O=no, 2= yes 
n Incoming logical links? O=no, 4= yes 


o 1 logical link/execution? 8=no, 0=yes 
s Sleep on pending message? 0 = no, 16 = yes 


Buffer maximum, 1 to 32767 bytes: Maximum amount of 
monitor’s buffer pool space to be used for pending local 
message data. Negative or 0 value indicates no such space 
is to be used for local message data. 


Message maximum, 0 to 255: Incoming local messages are 
not queued if the total number of pending messages for the 
program is greater than this value. 


Link maximum, 0 to 63: Incoming requests for logical links 
are rejected if the total number of links for the program is 
greater than this value. 


Ignored. 


Reserved - must be zero if passed. 
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Data Returned: 
No meaningful data is returned. 


Discussion: 
name 


The logical name is a string containing one to six characters. Valid characters 
are uppercase alphanumerics and the special characters “$”? (dollar sign), “.” 
(period), and “_” (underline). The name is left-justified in the string and (if 
necessary) padded to six characters with spaces. Leading or embedded spaces 
are invalid. If no name is to be specified (that is, the logical name is null), the 
string should consist of 6 spaces. 


The name is used to identify the calling program for queuing messages from 
local or network programs. Local programs can address the calling program by 
the logical name. Network programs can use either the logical name or the 
object type code, if one is declared. 


If the logical name is null, only network access by object type is allowed (see 
discussion of name, objtyp, and access). Otherwise, the logical name must be 
nonnull and unique. 


objtyp 


An object type code is another form of network addressing. As discussed in 
Section 3.2.1, the object type defines some service that the program performs. 
If the calling program is addressed by object code alone (name is null and 
access indicates network access only), multiple copies of the program can be 
executed simultaneously. Unlike name, the object type code need not be 
unique — multiple copies of a program can declare their identity with the 
same type code simultaneously. If name is null, objtyp cannot be zero. (Net- 
work addressing is discussed in detail in Section 4.1.) 


Acceptable values for the object type code range from 0 through 255. The 
value 0 indicates that object code addressing is not being used for the calling 
program. The range from 1 to 127 is reserved for DECnet use (see Appendix 
A). The range from 128 to 255 is available for definition and use by a network 
installation. 


access 


This field contains the sum of five bit values (/% + p% + n% + s% + 0%) that 
are used to determine access to the declaring program and to modify certain 
aspects of the message operations. 


Three of these bit values (/, p, and n) limit the types of senders that are 
allowed to queue messages for the calling program. They do not, however, 
limit the kind of messages that can be sent. 


If | = 0, messages from local senders will not be queued for the calling pro- 
gram. (Local senders who use the network functions are considered network 
senders in this context.) If | = 1, messages from local senders will be queued. 
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If p = 0, incoming messages from both local privileged and local nonprivileged 
senders will be queued for the calling program. If p = 2, incoming messages 
from local senders will be queued only if the sender is privileged. (This bit is 
ignored if / = 0, that is, if no local senders are allowed.) 


If n = 0, incoming requests for logical links are rejected by NSP. If n = 4, 
incoming Connect Initiate Messages are passed on to the receiver, subject to 
the declared link maximum (/max). In this case, the program must provide its 
own protection from unauthorized access, if necessary. 


Table 5-1 summarizes access code values and the access permitted for each. 


Table 5-1: Types of Receiver Access 


Access Code Network Local Senders Local Senders 
(n%+p%+I%) Logical Links Privileged Allowed 

0 no no no 

1 no no yes 

2 no no no 

3 no yes yes 

4 yes no no 

5 yes no yes 

6 yes no no 

7 yes yes yes 


Bit value o is used to regulate single-link programs, modifying the function of 
the program’s declared link maximum (Imax). If o = 0, incoming requests for 
logical links do not affect the program’s link maximum. If o = 8, however, 
after queuing an incoming Connect Initiate Message to the receiver, NSP sets 
the program’s link maximum to zero, inhibiting all further incoming connect 
requests. This, in effect, modifies the meaning of the link maximum from 
“one link at a time” to “one link per program execution.” 


By setting this “one-shot” bit to 8, a program prevents the possibility that 
NSP will queue a Connect Initiate Message for it after its one logical link is 
disconnected and before it issues a Remove Receiver call. For example, the 
DECnet/E FAL utility sets the one-shot bit to 8 and declares a link maximum 
of 1. Once FAL is started as the result of an incoming request from a remote 
NFT utility, NSP queues the Connect Initiate Message and zeros the link 
maximum. Thus, there is no possibility that another incoming connect re- 
quest could be queued for that copy between the time that NFT breaks the 
first link and the time that FAL issues its Remove Receiver call. This ensures 
that each incoming connect request starts a new copy of FAL. 


Bit value s is used to modify the function of the RSTS/E conditional Sleep 
monitor call. If s = 0, any unreceived messages queued for the program will 
block the execution of a conditional Sleep call. This is the normal RSTS/E 
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function. If s = 16, however, the monitor will not check the program’s message 
queue when determining whether or not it should in fact suspend program 
execution. Several other conditions (such as a delimiter received on an open 
terminal) can still block the sleep, but a pending message will not. 


name, objtyp, and access 


The system checks the values of the name, objtyp, and access fields to ensure 
that they are consistent. For example, a null logical name and an access code 
allowing local senders would be inconsistent since local senders can address 
the program by logical name. The system validates these arguments as shown 
in Table 5-2. If the arguments are invalid, the system will reject the Declare 
Receiver call, returning an error (ERR = 18). If the arguments are valid, the 
system allocates a small buffer to hold the information passed. If no buffers 
are available, the call will fail with an error (ERR = 4). A retry may be 
successful. 


Table 5-2: System Validation of Name, Object, and Access Parameters 


Access Code Senders Object 
(n%+p%+I%) Permitted Type Logical Name 


0,2 None Ignored Ignored. 
1,3 Local only Ignored Must be nonnull and unique. 
4,6 Network only Zero Must be nonnull and unique. 


Nonzero If the logical name is null (at least 
one leading binary zero byte), the 
only access permitted is by object 
type. Multiple copies of the pro- 
gram can coexist. 


If the logical name is nonnull, it 
must be unique. Network senders 
can refer to the calling program by 
name or by object type. Only one 
copy of the program using this logi- 
cal name can execute at any given 
time. 


5,7 Network/Local Any value Must be nonnull and unique so that 
local senders can refer to the calling 
program by logical name. Network 
senders can use name or object type 
(if object type + 0). Only one copy 
of the program using this logical 
name can execute at any given 
time. 


bmax 


Until a Receive system call is executed, a pending message occupies system 
buffer space. One 16-word buffer from the monitor’s buffer pool is used for 
user- or DECnet-defined parameters and other system-specific information. 
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Additional buffer space for the message data is usually allocated from the 
extended buffer pool. If an extended pool does not exist or no space is avail- 
able there, the monitor’s buffer pool is used. 


Because the monitor pool is a critical system resource, the receiver must set a 
limit on the amount of space to be used on its behalf. The bmax parameter 
sets a limit (1 to 32767 bytes) on the total monitor pool space to be used for 
the user data portion of messages. 


When this buffer maximum is exceeded, Local Data Messages are no longer 
queued for the program. NSP will return an error to any local program that 
tries to send a Local Data Message to the program at this point. Network 
messages will be queued regardless of the declared buffer maximum but any 
monitor pool space used will be counted against the maximum. 


A zero or negative value indicates that the monitor’s buffer pool is not to be 
used for the user data portion of pending Local Data Messages. 


mmax 


The message maximum (mmax) limits the number of messages that will be 
queued for the calling program. The value can range from 0 to 255. 


NSP keeps a count of the total number of messages queued for each declared 
receiver. When one of these counters equals or exceeds the message maximum 
set by the receiver: 


1. Incoming Local Data Messages are no longer queued for the receiving 
program. An error is returned to the local sender. 


2. Incoming Connect Initiate Messages cause NSP to determine if another 
copy of the program can be started automatically (see Section 4.1.2). If 
not, NSP rejects the connection and the Connect Initiate Message is not 
queued. A Connect Reject Message is returned to the sender. 


3. An incoming Network Data Message causes NSP to inhibit incoming data 
messages on that particular logical link and to negatively acknowledge 
(NAK) the message. This forces the remote system to retransmit when 
flow is reenabled. (See Section 4.2.2 for further details on backpressure 
flow control.) 


Imax 


The link maximum (/max) limits the number of incoming requests for logical 
links that will be queued for the calling program. The value can range from 0 
to 63. 


If the number of links currently active is greater than or equal to /max when a 
remote Connect Initiate Message is received for the program, the local NSP 
determines if another copy of the program can be started automatically (see 
Section 4.1.2). If not, NSP rejects the connection and the Connect Initiate 
Message is not queued. A Connect Reject Message is returned to the sender. 


By declaring a small link maximum, a program can avoid the overhead of 
responding to remote Connect Initiate Messages when it is known beforehand 
that the program can only handle a limited number of logical links. 
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A zero value for Imax has the same effect as setting n = 0 in the access control 
field. That is, incoming requests for logical links are rejected by NSP. The 
Imax parameter does not limit the number of logical links that can be initi- 
ated by the program. 


Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 
Network operations have been terminated due to an internal error. Notify the 
system manager. 
3 ACCOUNT OR DEVICE IN USE 
The calling job already exists in the system’s list of declared receivers. This error 
can indicate a logic error in the program or that a previous program running under 
the same job number failed to remove itself from the receiver list before terminat- 
ing. In the latter case, a Remove Receiver call should be issued, followed by 
another Declare Receiver call. 
It is common practice to issue a Remove Receiver call immediately before the 
Declare Receiver call. 
4 NO ROOM FOR USER ON DEVICE 
There were no small buffers available to hold the arguments passed with the 
Declare Receiver call. Since the system’s use of small buffers is dynamic, a retry 
may succeed. 
10 PROTECTION VIOLATION 
The calling program must be privileged at the time the Declare Receiver call is 
issued. 
16 NAME OR ACCOUNT NOW EXISTS 
The logical name passed in bytes 5-10 is being used by another job. 
18 ILLEGAL SYS() USAGE 
An inconsistency was found in the arguments passed. See name, object, and 
access discussion. 
Example: 


The following example shows a receiver declaration allowing only network 
access via logical links. The logical name is ADMIN and no object type code is 
used. Since local messages are not an issue, the buffer maximum (BMAX) is 
set to zero. The message maximum (MMAX) is set to 10. If more than 10 
messages accumulate in the program’s pending message queue, an incoming 
Connect Initiate Message will cause NSP to send back a Connect Reject 
Message to the remote program and any further incoming Data Messages will 
cause NSP to inhibit incoming message flow on all the program’s logical links 
because of the backpressure condition. Likewise, the link maximum (LMAX) 
is set to 1. When the program has established one logical link, an incoming 
Connect Initiate Message will cause NSP to send back a Connect Reject 
Message to the remote program. 
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LNAMES = “ADMIN " 
ACCESS% = 4% 
BMAK% = O% 
MMAX% = 10% 
LMAK% = 1% 


! 

! DECLARE RECEIVER EXAMPLE 

\ 

X$ = SYS(CHR$(6%)+CHRS$(22%)+CHR$(1%)+CHR$(0%) 
+LNAMES + STRING$(10%+0%) 
+CHRS(0%) 
+CHR$ (ACCESS%) 
+CHRS(BMAKZ) + CHRS(SWAPZ(BMAX%) ) 
+CHRS (MMAX%Z) 
+CHRS(LMAX%Z)) 
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5.3 Remove Receiver (Local and DECnet) 


The Remove Receiver system call removes the specified job from the system’s 
list of declared receivers. All pending messages are discarded and any active 
logical links are aborted. This call should be executed at the completion of 
message processing. This prevents unwanted messages from accumulating in 
the queue of pending messages. 


Privileged programs can remove other RSTS/E jobs with this call, although 
normally only system utility programs would do this. 


Data Passed: 


Bytes Value Description 
1 CHR$(6%) SYS call to FIP. 
2 CHR$(22%) Send/receive function code. 
3 CHR$(0%) Remove Receiver subfunction code. 
4 CHR$(0%) Zero, to remove the calling job (normal usage), 
or or 
CHR$(jobx2%) Job number times two, to remove another local RSTS/E 
job. Only privileged programs can issue this call with byte 4 
+0. 
5-12 0% Reserved - must be zero if passed. 
13-16 0% Ignored. 
17-40 0% Reserved - must be zero if passed. 


Data Returned: 


No meaningful data is returned. 


Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 

Network operations have been terminated due to an internal error. Notify the 
system manager. 

10 PROTECTION VIOLATION 
The caller is nonprivileged and has attempted to remove another job (that is, byte 
4 is nonzero). 

18 ILLEGAL SYS() USAGE 
The number passed in byte 4 was odd. Byte 4 must be zero to remove the calling 
job, or job number times two to remove another job. 

Example: 


The following example shows a typical Remove Receiver call: 


| EXAMPLE OF REMOVE RECEIVER 


X$ = SYS(CHR$(G%) + CHR$(22%) + CHRS(0Z)) 
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The Get Local Node Parameters system call returns information to the calling 
program concerning the local node’s network parameters. Data returned in- 
cludes the node’s name, address and alias (if any), and the default user’s 
account to be used when an incoming Connect Initiate Message does not 
specify accounting information. (See the DECnet/E System Manager’s Guide 
for a discussion of alias and Section 4.1.4 of this manual for a discussion of the 
default user’s account.) 


Data Passed: 


Bytes Value Description 

1 CHR$(6%) SYS call to FIP. 

2 CHR$(22%) Send/receive function code. 

3 CHR$(-19%) Get Local Node Parameters subfunction code. 
4 CHR$(1%) Must be set to “1”. 

5-40 0% Reserved - must be zero. 


Data Returned: 


The local node network parameters are returned to the calling program in the 
target string. The format of the information is as follows: 


Bytes Value Description 
1-2 — Not meaningful - should be ignored. 
3 CHR$(-19%) Get Local Node Parameters subfunction code. 
4 — Not meaningful - should be ignored. 
5-10 name$ Local node name: 1 to 6 characters. Left-justified with 
space fill to 6 characters. 

11-20 — Not meaningful - should be ignored. 

21-22 number% Local node number; 1 to 255. 

23-28 alias$ Local node alias: 1 to 6 characters. Left-justified with space 
fill to 6 characters. If no alias is defined, 6 spaces are re- 
turned. 

29-30 ppn% Default project-programmer number: Byte 29 = program- 


mer number, byte 30 = project number. Or both zero if 
none defined. 


31-40 — Not meaningful - should be ignored. 
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Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 

Network operations have been terminated due to an internal error. Notify the 
system manager. 

62 NO RUN-TIME SYSTEM 
NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 

66 MISSING SPECIAL FEATURE 
DECnet was not installed at system generation time. The network functions can- 
not be executed. 

Example: 


The following example illustrates the Get Local Node Parameters call: 


! EXAMPLE OF GET LOCAL NODE PARAMETERS 


X$ = SYS(CHR$(6%) + CHR$(22%) + CHRS(-19%) + CHRS(1%)) 
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(DECnet) 


The Log User Event call permits a user-written program to queue an event to 
the system event processor for logging. Before the event is logged, it is time- 
stamped by the system in the standard Network Information and Control 
Exchange (NICE) protocol format. The system manager can use the normal 
network management SET and CLEAR LOGGING commands to control the 
filtering of these events. Optional data can accompany a user event. 


NOTE 


This system call performs a highly specialized function which 
requires a great deal of special knowledge of DECnet and the 
DIGITAL Network Architecture (DNA). It is provided as a 
convenience for the sophisticated network user and is not in- 
tended for normal network programs. 


Data Passed: 


Bytes 


—- CO NO Ke 


13-14 


15-16 


17-20 
21-22 
23 
24-40 
41+ 


Yalue Description 

CHR$(6%) SYS call to FIP. 

CHR$(22%) Send/receive function code. 

CHR$(-10%) Log User Event subfunction code. 

CHR$(evmod%) Error return modifier. If 1, log ‘“‘missed event” message if 
event queue is full; if 0, return NOROOM status return. 

evcode% Event code representing the class (evcls%) and type 
(evtyp%) of the user event. This two-byte integer is formed 
as follows: 

evcode = eucls * 64% + evtyp 

0% Reserved - must be zero. 

CHR$(chnl%) Channel number of buffer containing the optional user data 
to be passed to the event logger for processing. If 0, this 
data is passed as part of the string. 

CHR$(0%) Reserved - must be zero. 

length% Length, in bytes, of data to be passed from the I/O buffer, 0 
to 200. If 0, the number of bytes equals the buffer size 
minus the offset. Ignored if chnl = 0. 

offset % Offset, in bytes, from the beginning of the buffer. If 0, the 
data starts at the beginning of the buffer. Ignored if chnl = 
0. 

0% Reserved - must’be zero. 

enval% Identifier of the entity with which this event is concerned. 

CHR$(entyp%) Type of entity with which this event is concerned. 

0% Reserved - must be zero. 

data% Optional user data, if sent as part of the string. Maximum 


of 200 bytes. Ignored if chnl + 0. 
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2 


2 


3 


Data Returned: 


No meaningful data is returned. 


Discussion: 
evmod 


This parameter specifies what the system should do if it is unable to log the 
user event due to lack of resources. If eumod is set to zero, the call terminates 
with an error of NOROOM (ERR = 4); the program can retry logging the 
event after a short delay. If eumod = 1, the system logs a “missed event” event 
message, and the call completes successfully. 


Note that in the second case, the user data is not logged. The system merely 
logs the fact that it has lost some unidentified data. This is identical to the 
procedure followed with DECnet internal events when the event queue is full 
or there are no more small buffers. 


evcode 


This parameter is a two-byte integer representing the class (evcls%) and type 
(evtyp%) of the user event to be logged. The class and type are packed into 
one two-byte value as follows: 


evcode = eucls * 64% + evtyp 


Events are divided into classes, according to the DNA layer from which they 
originate. Classes 480 to 511 are reserved for customer-specific events. How- 
ever, DECnet/E supports only class 480. Thus, evcls must be 480. The event 
type, evtyp, must be in the range of 0 to 31. 


enval 


This parameter associates a value to the entity specified by the entyp parame- 
ter. If the entity is a node, enval should be set to the node address. If the 
entity is a line or a circuit, enval should be set to the address of the Device 
Data Block (DDB) maintained for the device. 


entyp 


This parameter specifies the entity type with which the event is concerned. 
There are four entity types supported by DECnet/E, defined as follows: 


-1 No specific entity 


0 Node 

1 Line 

3 Circuit 
choi 


The chnl parameter can be a number from 1 to 12, indicating which channel 
buffer contains the user data to be processed with the event. Or it can be 0, 
indicating that this information is appended to the SYS call string. 
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If this data is included, it must be in NICE protocol format. Basically, this 
means that the data should be formatted in a 3-part field: a parameter type, a 
data type, and a parameter value. DECnet parameter types can be used if the 
event concerns a node, a circuit, or a line. In this case, the event logger will 
output standard descriptive text for the specific parameter. If a DECnet pa- 
rameter type is not used, parameter type in the range of 3900 to 4095 can be 
specified. (See the DIGITAL Network Architecture, Network Management 
Functional Specification, Version 3.0.0, for further information on event defi- 
nitions and parameters.) 


Up to 200 bytes of data can be passed to the event logger for processing. 
length 


The length parameter indicates how many bytes are to be processed from the 
channel buffer. Up to 200 bytes of data can be passed. 


If length = 0, the number of bytes processed is determined from the offset 
parameter and the size of the entire buffer, as defined by the RECORDSIZE 
option in the OPEN statement for the buffer. That is, the number of bytes 
passed to the event processor is equal to the buffer size minus offset. This size 
must also be less than or equal to 200. 


The length parameter is ignored if chnl = 0; that is, if the data is appended to 
the SYS call string. 


offset 


If an I/O buffer is used, the user data is assumed to be in the buffer in 
contiguous bytes. The size of the offset (in bytes) is indicated with this pa- 
rameter. For example, if offset = 20, the user data begins in byte 21: 


byte 1 20] 21 


whole buffer 


The offset field is ignored if chnl = 0. 
data 


The event data to be passed to the event logger for processing can be included 
as part of the SYS call string, rather than in an I/O buffer. If this is the case, 
the data is passed in these bytes. 


Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


(continued on next page) 
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Error Text and Meaning 


Example: 


NO ROOM FOR USER ON DEVICE 


The event queue is full or there are no small buffers available to hold the event. A 
retry may succeed. (This error is returned only if eumod = 0.) 


CAN’T FIND FILE OR ACCOUNT 
The event logger is not running. Have the system manager start the event logger. 
PROTECTION VIOLATION 


The calling program must be privileged at the time the Log User Event system 
call is issued. 


ILLEGAL SYS() USAGE 
The parameters passed are either inconsistent or invalid. 
MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


The following example illustrates the logging of a user event, class 480. and 
type 3. The entity node number is 135. The optional data passed for process- 
ing is part of the SYS call string and consists of an lla parameter number 
(2130) and value. A ‘“‘missed event” is logged if the event itself cannot be. 


EVMOD% 
EVCLS% 
EVTYP% 
EVCODE% 
ENTYP% 
ENVAL% 
PRMTYP% 
DATTYP% 
DATYVAL% 
DATA 


+H non Ht bonon to ono 


! EXAMPLE 


| 


1% 

480% 

3% 

EVCLS% * G4% + EVTYP% 

O% 

135% 

213% 

2h 

40960% 

CHRS(PRMTYP%) + CHRS(SWAPZ(PRMTYP%)) + CHRS(DAPTYP%) 
CHRS(DATYALZ) + CHR (SWAPZ(DATVALZ) ) 


OF LOG USER EVENT CALL 


K$ = SYS(CHR$(6%) + CHR$(22%) + CHRS(-10%) 


+ 


++ et et 


CHR$ (EYMODZ >) 

CHR$(EVCODE%) + CHRS(SWAPZ(EVCODEZ) ) 
STRING$(14%+0%) 

CHRS(ENVALZ) + CHRS(SWAPZ(ENVALZ) ) 
CHRS(ENTYP%) 

STRING$(17%+0%) 

DATAS 


The Log User Event system call in the previous example generates the follow- 
ing event message: 


Event type 480.3 

Occurred 14-Dec-81 15:31:39.7 on node 135 (GROK) 
Node address 135 (GROK) 

Parameter #2130 = 40960 
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There are nine separate send calls — one local and eight network. Each of 
these calls causes NSP to format a message that is then either queued to a 
local program or transmitted across the network to a remote program. 


5.6.1 Send Local Data Message (Local) 


The Send Local Data Message system call sends up to 532 bytes of user data 
to another program in the local RSTS/E environment. The other program 
must be a declared receiver of local messages. If the other program has de- 
clared that only privileged local senders are allowed, the calling program must 
be privileged. The receiving program is identified in the call by either its job 
number or by the logical name with which it declared itself a receiver. 


Up to 512 bytes of user data can be sent from a channel buffer or appended to 
the string. An additional 20 bytes of user data can be sent from the string. 


Data Passed: 


Bytes Value Description 

1 CHR$(6%) SYS call to FIP. 

2 CHR$(22%) Send/receive function code. 

3 CHR$(-1%) Send Local Data Message subfunction code. 

4 CHR$(jobx2%) Job number (times two) of the local job to receive the mes- 
sage. If 0, name (bytes 5-10) is used to identify the in- 
tended receiver. 

5-10 name$ Declared logical name of local program to receive the mes- 
sage. 1 to 6 characters, left-justified, with space fill. Used if 
jobx2 = 0, ignored otherwise. 

11 CHR$(chnl%) Channel number of buffer containing the message data, 1 to 
12. If 0, the data is to be sent as part of the string. 

12 CHR$(0%) Reserved -— must be zero. 

13-14 length% Length, in bytes, of the message data to be sent from the 
buffer, 1 to 512. If 0, the number of bytes sent equals buffer 
size minus offset. Ignored if chnl = 0. 

15-16 offset % Offset, in bytes, from the beginning of the buffer where the 
message data begins. If = 0, the message data is assumed to 
start at beginning of the buffer. Ignored if chnl = 0. 

17-20 0% Reserved - must be zero. 

21-40 param$ Optional user parameter string. Up to 20 bytes of user data 
can be passed here as part of the string. 
41+ data$ 0 to 512 bytes of message data to be sent to the local pro- 


Data Returned: 


gram, if sent as part of the string (that is, if chni = 0). 
Ignored if chnl + 0. 


No meaningful data is returned. 
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Discussion: 
jobx2 


If jobx2 = 0, the message data is sent to the program identified by the logical 
name field. Otherwise, the message data is sent to the program whose job 
number (times two) is equal to jobx2. For example, if jobx2 = 8, the message is 
sent to job 4. 


name 


The logical name identifies the intended local receiver when the jobx2 param- 
eter = 0. The intended receiver must have declared its identity with this name 
in its Declare Receiver call. The name consists of one to six characters, left- 
justified in the field and, if necessary, padded to six characters with spaces. 
Valid characters are uppercase alphanumerics and the special characters “‘$” 
(dollar sign), “‘.” (period), and “‘__”’ (underline). Leading or embedded spaces 
are invalid. This field is ignored when jobx2 + 0. 


chnl 


The chnl parameter is either an integer from 1 to 12, indicating which I/O 
buffer contains the message data, or the value zero, indicating that the mes- 
sage data is part of the SYS call string. 


length 


The length parameter indicates how many bytes are to be sent from the I/O 
buffer. The maximum value for length is 512. If length = 0, the number of 
bytes sent is determined from the offset parameter and the size of the entire 
buffer, as defined by the RECORDSIZE option in the OPEN statement that 
allocated the buffer. That is, the number of bytes sent is equal to the buffer 
size minus offset. This size must also be in the range of 1 to 512. 


The length field is ignored if chn/ = 0, that is, if the user message data is 
appended to the SYS call string. 


offset 


If an I/O buffer is used, the user data can be offset from the beginning of the 
buffer. The size of the offset (in bytes) is indicated with the offset parameter. 
For example, if offset = 20, the user data begins in byte 21: 


The offset field is ignored if chnl = 0. 
byte 1 20 | 21 


whole buffer 


param 


The optional param string allows up to 20 additional bytes of user data to be 
passed. It is delivered to the local program separate from the message data. 
For example, when a BASIC-PLUS program issues a Receive call that returns 
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a Local Data Message, the parameter data is returned in the target string for 
the Receive call and the message data is returned in the channel buffer speci- 
fied in the Receive call. 


data 


The user data (if any) can be sent from the SYS call string (data) or from the 
I/O buffer specified by the chnl parameter. Up to 512 bytes can be sent in 
either case. If a buffer is used, remember that length bytes will be transmitted 
and that the first offset bytes in the buffer will not be sent. 


Possible Errors: 


ERR 
Value Error Text and Meaning 


4 NO ROOM FOR USER ON DEVICE 


The number of pending messages for the intended local receiver is at its declared 
maximum. The calling program should try again later. If this error occurs repeat- 
edly, the receiver is not processing messages often enough. 


5 CAN’T FIND FILE OR ACCOUNT 


The intended local receiver could not be located in the system’s list of declared 
receivers. The receiver must be declared (with a Declare Receiver call) before any 
data can be transmitted to it. 


9 1/0 CHANNEL NOT OPEN 


The channel specified in byte 11 of the data passed is not open. The program must 
OPEN the channel to allocate a buffer for message operations. 


10 PROTECTION VIOLATION 


Some access violation has occurred. Either the receiver does not allow any local 
senders or the sender is nonprivileged and the receiver allows only privileged 
senders. 


18 ILLEGAL SYS() USAGE 


The quantity in byte 4 (jobx2) is odd. Byte 4 must be 0 or the receiver’s job 
number times two. 


31 ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are inconsistent. The follow- 
ing must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be less than or equal to 512. 


The offset and length fields are checked for validity whenever chnl (byte 11) + 0. 
32 NO BUFFER SPACE AVAILABLE 


System buffers are currently not available to store the message for the intended 
local receiver. A later retry may proceed without error. 
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Example: 


This example shows a local send to a program named “HARVEY”. The user 
data is sent from the SYS call string, beginning in byte 41. 


MSG$ = "THIS MESSAGE IS SENT FROM THE SYS CALL STRING" 
! 


! EXAMPLE OF LOCAL DATA SEND 
\ 


X$ = SYS(CHRS$(6%) + CHR$(22%) + CHRS(-1%) + CHR#(0%) 


+ "HARVEY" + STRING$(30% 10%) 
+ MSG$) 
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5.6.2 Send Connect Initiate Message 


(DECnet) 


The Send Connect Initiate Message call requests a logical link to another 
program. The other program is identified with a Connect Data Block and the 
user link address by which the calling program will refer to the link is estab- 
lished. The flow control option and maximum amount of user data for 
received Network Data Messages are also specified here. Up to 16 bytes of 
optional user data can be passed to the other program. 


Data Passed: 


Bytes 


13-14 


15-16 


17-22 
23 
24 


25-26 


27-40 
41-160 


161+ 


Value 


CHR$(6%) 
CHR$(22%) 
CHR$(-2%) 
CHR$(ula%) 
0% 
CHR$(chnl%) 


CHR$(0%) 
length% 


offset % 


0% 
CHR$(llmod%) 


CHR$(0%) 


rmax% 


data$ 


Data Returned: 


Description 


SYS call to FIP. 

Send/receive function code. 

Send Connect Initiate Message subfunction code. 
User link address, 1 to 255. 

Reserved - must be zero. 


Channel number of buffer containing the Connect Data 
Block and optional user data, 1 to 12. If 0, these are to be 
sent as part of the string. 


Reserved - must be zero. 


Length, in bytes, of information to be sent from the I/O 
buffer (including the Connect Data Block), 120 to 136. If 0, 
the number of bytes sent equals buffer size minus offset. 
Ignored if chnl = 0. 


Offset, in bytes, from the beginning of the buffer where the 
Connect Data Block begins. If 0, the data starts at the 
beginning of the buffer. Ignored if chni = 0. 


Reserved — must be zero. 


Local link modifier. Indicates the type of flow control: 0 = 
none, 1 = segment, 2 = message. 


Reserved - must be zero. 


Maximum amount of user data (in bytes) that the local 
program will accept in one Network Data Message from the 
remote program. 


Reserved - must be zero. 


The Connect Data Block, if sent as part of the string (if 
chnl = 0). Ignored if chnl + 0. (In either case, the Connect 
Data Block must = 120 bytes.) 


Optional user data, if sent as part of the string. Maximum 
of 16 bytes. Ignored if chnl + 0. 


No meaningful data is returned. 
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Discussion: 
ula 


The user link address (ula) can be an integer from 1 to 255. This value will be 
used in later calls to refer to this link (assuming that the link being requested 
by this call is accepted by the remote NSP and the remote program). 


The ula must be unique within the program at any given time. That is, one 
program cannot have two different logical links with the same ula at the same 
time. 


choi 


The chnl parameter can be a number from 1 to 12, indicating which channel 
buffer contains the Connect Data Block and the (optional) message data. Or 
it can be 0, indicating that this information is appended to the SYS call 
string. 


length 


The length parameter indicates how many bytes, including the Connect Data 
Block, are to be sent from the channel buffer. Since the Connect Data Block is 
120 bytes long and the optional message data can be from 1 to 16 bytes long, 
acceptable values for length in this request run from 120 to 136; or it can be 
zero. 


If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the buffer. That is, the number of bytes sent is equal 
to the buffer size minus offset (which must still be in the range 120 to 136). 


The length parameter is ignored if chnl = 0; that is, if the Connect Data Block 
and message data are appended to the SYS call string. 


offset 


If an I/O buffer is used, the Connect Data Block and message data are as- 
sumed to be in the buffer in contiguous bytes. They can be offset from the 
beginning of the buffer, and if so, the size of the offset (in bytes) is indicated 
with this parameter. For example, if offset = 20, the Connect Data Block 
begins in byte 21: 


byte 1 20 | 21 140| 141 


whole buffer 
The offset field is ignored if chnl = 0. 


Ilmod 


The llmod value indicates the type of flow control requested for this end of the 
logical link. 
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Acceptable values and meanings are: 


0 No flow control. 
1 Segment flow control. 
2 Message flow control. 


Flow control is described in detail in Chapter 4. Remember that flow control is 
independent for each end of a logical link. What is requested here applies only 
to this end of the link. If /Imod is nonzero, the calling program must issue 
Link Service calls to request Data Messages from the other program. 


rmax 


A program that has limited buffer space and is not designed to process large 
messages in small pieces (see the discussion of the /ength parameter for the 
Receive call, Section 5.7) can impose a limit on the amount of user message 
data it is willing to receive on a logical link. The rmax value specifies this 
limit in bytes. 


The size of the receive buffers allocated by NSP will itself limit the amount of 
data that can be passed in a single Network Data Message. If the maximum 
size set for NSP by Network Management is not large enough to handle the 
receive maximum as specified in rmax, the local NSP will alter the maximum 
to the smaller limit before forwarding the Connect Initiate Message to the 
remote node. If rmax = 0, NSP will supply the size of its receive buffers as a 
default value. (The calling program will be informed of any such change by a 
field in the Connect Confirm Message from the target program when the link 
is accepted.) 


The remote NSP uses this value to establish a transmit maximum for its end 
of the logical link. If the remote system is also a RSTS system, this transmit 
maximum is passed on to the remote program which must limit the amount of 
the user message data it transmits over the logical link according to this 
value. 


connect data block 


The Connect Data Block identifying the remote node and program can be 
specified as part of the SYS call string (cdb) or it can be given in the I/O 
buffer (chnil + 0). In either case, it must be 120 bytes long. The format of the 
120-byte Connect Data Block is shown in Figure 5-2 and described in detail in 
Table 5-3. 


data 


Optional user data (up to 16 bytes) can be given following the Connect Data 
Block as part of the SYS call string (data) or following the Connect Data 
Block in the I/O buffer (chnl + 0). 
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Figure 5-1: Format of Connect Data Block on Send Connect 
Initiate Message 


Table 5-3: Format of Connect Data Block on Send Connect 
Initiate Message 


Bytes Content 


1-6 Remote Node. 1 to 6 uppercase, alphanumeric characters giving the name of 
the remote node to which the Connect Initiate Message is to be sent. This name 
must contain at least one alphabetic character and names shorter than six 
characters must be left-justified and padded to six characters with spaces. If no 
node name is specified (that is, the request is directed to a program at the local 
node), this field should contain 6 spaces. 


7-26 Remote Program. Identifies the remote program to which the Connect Initiate 
Message is directed as either an object type (general function) or a specific 
entity (program, task, or process). This identification is given in one of three 
formats: 


Format 0 
The remote program is identified by object type code alone. The fields are: 
Bytes Content 


7 Zero, to indicate a format 0 name. 
8 Object type code of the remote program. 
9-26 Zero (not used). 


(continued on next page) 
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Table 5-3 (Cont.): Format of Connect Data Block on Send Connect 
Initiate Message 


Format 1 
The remote program is identified by a descriptor. The fields are: 
Bytes Content 


7 One, to indicate a format 1 name. 

8 Normally zero. This byte should be zero unless the target DECnet 
system allows identification by both name and object type code on 
incoming connect requests (DECnet/E does not). If nonzero, this byte 
is interpreted as the object type code of the remote program for which 
the Connect Initiate Message is intended. 


9 Reserved — must be zero. 

10 Length of descriptor, in bytes, 0 to 16. Gives the number of characters 
to be interpreted as the program descriptor in the following field (bytes 
11-26). 


11-26 Remote program descriptor (left-justified). For a DECnet/E program, 
this is the logical name that the remote program defined in its Declare 
Receiver system call. For other systems, it is the descriptor used to 
register the program for network operations. 


Format 2 


This format allows identification of the remote program by name or object type 
code and by the group and user codes under which the remote program is 
accessible on the remote system. (The group and user codes refer to what is 
called the project-programmer number on some DIGITAL systems, including 
RSTS/E. Other systems refer to these codes as the user identification code, or 
UIC.) DECnet/E systems use only the object type code or descriptor to find or 
start the target program for which a connect request is intended. The group and 
user codes are simply passed on to the target program for its own checking. 
Other DECnet systems can handle an incoming connect request in format 2 
differently. 


The subfields are defined as follows: 


Bytes Content 


7 Two, to indicate a format 2 name. 

8 Object type code of the remote program, if applicable. If zero, the 
descriptor must be used. 

9 Reserved - must be zero. 

10 Length of descriptor, 0 to 12. Gives the number of characters to be 
interpreted as the program descriptor in the following field (bytes 11- 
22). 


11-22 Remote program descriptor, if this is used instead of object type code. 
The descriptor should be left-justified in the field. 

23-24 Remote group code. Binary value giving the group number under which 
the remote program is running or is to be started. Corresponds to the 
project number in a RSTS/E project-programmer number. This value 
is not used by DECnet/E systems but is simply passed on to the receiv- 
ing program. 

25-26 Remote user code. Binary value giving the user number under which 
the remote program is running or is to be started. Corresponds to the 
programmer number in a RSTS/E project-programmer number. This 
value is not used by DECnet/E systems but is simply passed on to the 
receiving program. 


27-46 Local Program. This field is filled in by the local NSP using information that 
the local program specified in its Declare Receiver call. Any values passed by the 
user program in this field are ignored. 


(continued on next page) 
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Table 5-3 (Cont.): Format of Connect Data Block on Send Connect 


47-92 


93-120 


Initiate Message 


The information is passed to the remote system in format 2, as described previ- 
ously. Byte 27 is filled in with a value of 2. If the program declared its identity 
with object type alone, the object type code is passed in byte 28 and bytes 30-42 
are zero. If the program declared its identity with a logical name, or with a 
logical name and an object type code, the logical name is supplied in bytes 31-42 
and byte 28 is zero. The length of the logical name is given in byte 30. The 
project-programmer number under which the program is running is passed in 
bytes 43-46 as the group and user codes. The project number is in byte 43. The 
programmer number is in byte 45. Both are in binary format. 


Access Control Fields. These bytes can be used to define the calling program’s 
access rights to the remote system or to the remote program’s services. The idea 
is analogous to logging in on the remote system. The most rigorous checking 
done in a normal log-in on DIGITAL systems involves user identification, pass- 
word, and account number, so three fields are defined here for those items. 
However, overall DECnet design does not specifically require use of these fields 
at all, nor does it require that the fields be used as described. A DECnet/E 
system simply passes this information onto the receiving program. To determine 
what, if anything, a non-RSTS DECnet system requires in these fields, see the 
DECnet manual for that system. 


NOTE 


The DECnet/E utilities NFT and NETCPY, which use logical 
links to access remote files and devices, use these fields to estab- 
lish the local terminal user’s right to access the remote files and 
devices. Both utilities prompt the local user for log-in information 
to be used at the remote system and pass that information along 
in the Connect Data Block of the Connect Initiate Message. The 
remote FAL or receiving NETCPY checks this information before 
allowing the operation requested. 


Bytes Content 


47 Reserved - must be zero. 
48 Length of user identification information specified in the next field, 0 
to 16 bytes. 


49-64 User Identification. This field identifies the person or program request- 
ing the logical link. In RSTS/E terms, the user ID is analogous to the 
project-programmer number used at log-in. This information need only 
be specified here if it is required by the remote system or program. If it 
is not required, the length (byte 48) should be set to zero. 

65 Reserved - must be zero. 

66 Length of password information specified in the next field, 0 to 8 bytes. 

67-74 Password. A password is often used to verify access to a system under a 
particular user identification. In RSTS/E, this password is analogous to 
the password used in conjunction with the project-programmer number 
at log-in. A password supplied here must be acceptable to the remote 
system or program, if one is required. If not required, the length (byte 
66) should be set to zero. 


75 Reserved - must be zero. 
76 Length of the accounting information specified in the following field, 0 
to 16 bytes. 


77-92 Accounting Information. Many systems require a billing account num- 
ber in addition to user identification and password. The accounting 
field is provided for this purpose. Once again, such information need 
only be specified here if it is required by the remote system or program. 
If it is not required, the length (byte 76) should be set to zero. 


Reserved for future use. Currently ignored by DECnet/E but should be passed 
as zeros. 
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Possible Errors: 


ERR 
Value Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


3 ACCOUNT OR DEVICE IN USE 


A logical link is currently active for the calling program with the same user link 
address (ula) as specified in this Connect Initiate Message. A different ula must 
be used or the existing link must be disconnected. 


6 NOT A VALID DEVICE 
The node named in the Connect Data Block is not known to the system. 


9 1/0 CHANNEL NOT OPEN 


The channel specified by byte 11 of the call is not open. The program must OPEN 
the channel before using it for message operations. 


14 DEVICE HUNG OR WRITE LOCKED 


The node named in the Connect Data Block is known to the system but is cur- 
rently inactive. There is no physical communication path to the node. 


17 TOO MANY OPEN FILES ON UNIT 


NSP cannot allocate its local link address (lla) for the logical link. The maximum 
number of logical links allowed at the local RSTS/E node (some limit between 1 
and 63, as set by the system manager) has been reached. A later try may succeed. 
(See the system manager if the limit in effect is inadequate.) 


18 ILLEGAL SYS() USAGE 
One of several possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The Declare Receiver call for the calling program had a null logical name and 
a zero object type code. There is no way to identify the program to the remote 
system. Do a Remove Receiver call and reissue the Declare Receiver call. 


3. An invalid value was detected in one of the following fields: 
e Remote program field in the Connect Data Block. 
¢ One of the three access control fields in the Connect Data Block. 
e User link address (ula) given was zero. Valid values range from 1 to 255. 
e The llmod value (byte 23) must be 0, 1, or 2. 


e The remote descriptor length (byte 10 in the Connect Data Block) was 
nonzero, but the descriptor field was null (all zeros). 


22 DISK PACK IS LOCKED OUT 


NSP cannot create a new logical link because the physical line to the remote node 
or the local node itself has been scheduled for shutdown by the system manager. 


(continued on next page) 
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ERR 
Value Error Text and Meaning 
31 ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are invalid. The following 
must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 120 and 136. This encompasses 120 
bytes for the Connect Data Block and a maximum of 16 bytes of data. 


The offset and length fields are checked for validity whenever chnl (byte 11) #0. 


32 NO BUFFER SPACE AVAILABLE 
System buffers are not currently available to store this message. A later try may 
succeed. 

62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 


66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


Example: 


This example shows a Connect Initiate Message directed to a program with 
object type code 126 at node BOSTON. The Connect Data Block (CDB$) uses 
a format 0 name to address the remote program. The local program name is 
supplied by NSP and no access control fields are being used, so the rest of the 
Connect Data Block is filled with binary zeros to make up 120 bytes. 


A user link address of 13 is used, segment flow control is requested by the 
calling program, and a receive maximum of 256 bytes is specified. 


ULA% = 13% 'USER LINK ADDRESS = 13 
LLMOD% = 1% !SEGMENT FLOW CONTROL REQUESTED 
RMAX% = 256% !RECEIVE MAXIMUM SET TO 256 BYTES 
COBS = "BOSTON" + CHR#(0%) + CHR$(126%) + STRING$(112%:0%) 
! 
! EXAMPLE OF SEND CONNECT INITIATE 
! 
X$ = SYS(CHR#$(6%) + CHR$(22%) + CHR$(-2%) + CHRS(ULAZ) 
+ STRING$(18%:0%) + CHRS(LLMOD%) + CHRS(0%) 
+ CHRS(RMAXZ) + CHRS(SWAPZ(RMAXZ) ) 
+ STRING$(14%,0%) + CDBS + "TIME-CARD UPDATE") 
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5.6.3 Send Connect Confirm Message (DECnet) 


This system call is used to accept a remote program’s request for a logical 
link. The call establishes the user link address that the local program will use 
to refer to the link and identifies the link being accepted by the local link 
address assigned by the local NSP. The flow control option and receive maxi- 
mum are specified here and up to 16 bytes of optional message data can be 
passed to the remote program. 


Data Passed: 


Bytes Value Description 
1 CHR$(6%) SYS call to FIP. 
Z CHR$(22%) Send/receive function code. 
3 CHR$(-3%) Send Connect Confirm Message subfunction code. 
4 CHR$(ula%) User link address, 1 to 255. 
5-6 lla% Local link address (from bytes 5-6 of received Connect Ini- 
tiate Message). (See Section 5.7.2.) 
7-10 0% Reserved - must be zero. 

11 CHR$(chnl%) Channel number of buffer containing the optional message 
data, 1 to 12. If 0, the data is appended to the SYS call 
string. 

12 CHR$(0%) Reserved - must be zero. 

13-14 length% Length, in bytes, of data to be sent from the buffer, 1 to 16. 


If 0, the number of bytes sent equals buffer size minus 
offset. Ignored if chnl = 0. 


15-16 offset % Offset, in bytes, from the beginning of the buffer where the 
user data begins. If 0, the data starts at the beginning of the 
buffer. Ignored if chnl = 0. 


17-22 0% Reserved - must be zero. 

23 CHR3$(llmod%) Local link modifier, used to indicate the type of flow con- 
trol: 0 = none, 1 = segment, 2 = message. 

24 CHR$(0%) Reserved - must be zero. 

25-26 rmax% Maximum amount of user data (bytes) that the local pro- 


gram will accept in one Network Data Message from the 
remote program. 


27-40 0% Reserved - must be zero. 


41+ data$ Optional message data, if appended to the string. Maxi- 
mum of 16 bytes. Ignored if chnl +°0. 


Data Returned: 

No meaningful data is returned. 
Discussion: 

ula 


The user link address (ula) can be a number from 1 to 255. This value is used 
in later calls to refer to this link. The ula must be unique. That is, one 
program cannot have two logical links with the same ula at the same time. 
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Ila 


The local link address (lia) identifies the link being accepted. It is a number 
assigned by the local NSP when it received the Connect Initiate Message 
requesting the link. The local tink address is passed to the local program in 
bytes 5-6 of the received Connect Initiate Message to which this Connect 
Confirm Message is a positive response. (Section 5.7.2 shows the entire format 
of a received Connect Initiate Message.) 


chni 


The chnl parameter can be a number from 1 to 12, indicating which buffer 
contains the (optional) user data. Or it can be 0, indicating that this informa- 
tion is appended to the SYS call string. 


length 


The length parameter indicates how many bytes are to be sent from the 
channel buffer. Acceptable values for length in this request can range from 1 
to 16, or it can be zero. 


If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the buffer. That is, the number of bytes sent is equal 
to the buffer size minus offset. This size must also be in the range 1 to 16. 


The length parameter is ignored if chni = 0; that is, if the user data is 
appended to the SYS call string. 


offset 


If an I/O buffer is used, the user data is assumed to be in the buffer in 
contiguous bytes. The size of the offset (in bytes) is indicated with this pa- 
rameter. For example, if offset = 20, the user data begins in byte 21: 


byte 1 20 | 21 


whole buffer 
The offset field is ignored if chnl = 0. 


Ilmod 


The llmod value indicates the type of flow control requested for this end of the 
logical link. Acceptable values and meanings are: 


0 No flow control. 
1 Segment flow control. 
2 Message flow control. 


Flow control is described in detail in Chapter 4. Remember that flow control is 
independent for each end of a logical link — what is requested here applies 
only to this end of the link. If //mod is nonzero, the calling program must issue 
Link Service calls to request Network Data Messages from the remote pro- 
gram. 
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rmax 


A program that has limited buffer space and is not designed to process large 
messages in small pieces (see the discussion of the length parameter for the 
Receive call, Section 5.7) can impose a limit on the amount of user data it is 
willing to receive in one Network Data Message from the remote program over 
this logical link. The rmax value specifies this limit in bytes. 


The size of the receive buffers allocated by NSP will itself limit the amount of 
data that can be passed in a single Network Data Message. If the maximum 
size set for NSP by Network Management is not large enough to handle the 
receive maximum as specified by rmax, the local NSP will alter the maximum 
to the smaller limit before forwarding the Connect Confirm Message to the 
remote node. If rmax = 0, NSP will supply the size of its receive buffers as a 
default. 


The remote NSP uses this value to establish a transmit maximum for its end 
of the logical link. If the remote system is also a RSTS system, this transmit 
maximum is passed on to the remote program which must limit the amount of 
the user data it transmits in Network Data Messages according to this value. 


data 


Up to 16 bytes of optional user data can be passed as part of the SYS call 
string (data) or in the channel buffer (chnl + 0). 


Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 
Network operations have been terminated due to an internal error. Notify the 
system manager. 
3 ACCOUNT OR DEVICE IN USE 
A logical link is currently active for the calling program with the same user link 
address (ula) as specified in this Connect Confirm Message. A different ula must 
be used or the existing link must be disconnected. 
5 CAN’T FIND FILE OR ACCOUNT 
The local link address (lla) specified in bytes 5-6 does not correspond to any 
known logical link for the calling program. Either the lla is incorrect or the 
originating Connect Initiate Message has been cancelled. In the latter case, a Link 
Abort Message has already been queued for this link. Since no ula was ever 
established, an lla field is available in a received Link Abort Message identifying 
the link. 
9 1/O CHANNEL NOT OPEN 
The channel specified in byte 11 is not open. The program must OPEN the 
channel before using it for message operations. See Section 5.1.2. 
10 PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Connect Confirm Message for a 
link that is not waiting for confirmation or rejection will result in this error. For 
example, a second Connect Confirm Message for the same logical link will result 
in this error because the link is already established. 


(continued on next page) 
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ERR 
Value 


18 


31 


32 


62 


Error Text and Meaning 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The program has not issued a Declare Receiver call. All DECnet functions 
require the caller to be a declared receiver. 


2. An invalid value was detected in one of the following fields: 
e ula (byte 4) is 0. Acceptable values range from 1 to 255. 
e llmod (byte 23) must be 0, 1, or 2. 

ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are invalid. The following 
must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 0 and 16. 


BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


Example: 


In this example, a Send Connect Confirm Message system call is issued in 
response to a previously received Connect Initiate Message whose control 
information was returned to the target string A$. The MID function places the 
local link address from A$ in the string LLA$. Other parameters are similar to 
those in a Connect Initiate Message. 


LLAS = 
ULAZ = 
LLMOD% 
RMAX% 

\ 


MID( A$ 15% 52%) !'GET LOCAL LINK ADDRESS 

25% 'USER LINK ADDRESS = 25 

= 2% 'MESSAGE FLOW CONTROL REQUESTED 
512% 


! EXAMPLE OF CONNECT CONFIRM 


Xs = SYS(CHR$(6%) + CHR$(22%) + CHR$(-3%) + CHRS(ULAZ) 


+ LLAS + STRING$(16% 10%) 
+ CHRS(LLMODZ) + CHRS$(0Z) 
+ CHRS(RMAXZ) + CHRS(SWAPZ(RMAXZ) )) 
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5.6.4 Send Connect Reject Message (DECnet) 


Sending a Connect Reject Message rejects a remote program’s request for a 
logical link. The link is identified by the local link address established by the 
local NSP. Up to 16 bytes of optional user data can also be passed to the 
remote program. 


Data Passed: 


Bytes Value Description 

1 CHR$(6%) SYS call to FIP. 

2 CHR$(22%) Send/receive function code. 

3 CHR$(-4%) Send Connect Reject Message subfunction code. 

4 CHR(0%) Ignored. 

5-6 lla% Local link address (from bytes 5-6 of received Connect Ini- 
tiate Message). 

7-10 0% Reserved - must be zero. 

11 CHR$(chnl%) Channel number of buffer con:aining optional message 
data, 1 to 12. If 0, data is appended to SYS call string. 

12 0% Reserved - must be zero. 

13-14 length% Length, in bytes, of data to be sent from the buffer, 0 to 16. 


If 0, the number of bytes sent equals the buffer size minus 
offset. Ignored if chnl = 0. 


15-16 offset% Offset (in bytes) from the beginning of the buffer where the 
user data begins. If 0, the data starts at the beginning of the 
buffer. Ignored if chnl = 0. 


17-22 0% Reserved - must be zero. 


23-24 reason% Reason for rejection, if applicable. Can be 0 (normal case 
for user programs), 34 (access not permitted), or 36 (invalid 
accounting information). 


25-40 0% Reserved - must be zero. 
41-56 data$ Optional user data, if appended to the string. Maximum of 
16 bytes. Ignored if chni + 0. 


Data Returned: 

No meaningful data is returned. 
Discussion: 

Ila 


The local link address (lla) identifies the link being rejected. It is a number 
assigned by the local NSP when it received the Connect Initiate Message 
requesting the link. The //a is passed to the local program in bytes 5-6 of the 
received Connect Initiate Message to which this Connect Reject Message is a 
negative response. (Section 5.7.2 shows the entire format of a received Con- 
nect Initiate Message.) 
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chai 


The chni parameter can be a number from 1 to 12, indicating which buffer 
contains the (optional) message data to be passed to the remote program. Or 
it can be 0, indicating that this information is appended to the SYS call 
string. 


length 


The length parameter indicates how many bytes of user data, if any, are to be 
sent from the channel buffer. Acceptable values range from 1 through 16. This 
field is ignored if chnl = 0. 


If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the buffer. That is, the number of bytes sent is equal 
to the buffer size minus offset. This size must also be in the range 1 to 16. 


offset 


If a channel buffer is used, the user message data, if any, can be offset from 
the beginning of the buffer. The size of the offset (in bytes) is indicated with 
this parameter. For example, if offset = 20, the user data begins in byte 21: 


byte 1 20) 21 


whole buffer 
The offset field is ignored if chnl = 0. 


reason 


DECnet/E NSP allows a program to specify one of the following three reason 
codes: 0, 34, or 36. 


Most user programs will simply use 0. If any reason is supplied for rejecting 
the connection, it is passed in the 16-byte user data area. 


The values 34 and 36 are allowed so that DECnet/E support programs (such 
as FAL and NFT) can reject unauthorized or improper requests for access to 
local RSTS/E files in a manner agreed upon as part of the overall DECnet 
design. There is no reason for a user program to use these codes unless it talks 
to other programs that interpret them. All DECnet programs that are con- 
cerned with protecting against unauthorized access are designed to recognize 
these codes and take appropriate action, such as displaying an error message 
to a user, when they receive such a connect rejection. 


The value 34 indicates that the user ID and password subfields of the access 
control field in the Connect Data Block in the remote program’s Connect 
Initiate Message do not correspond to any valid user known to the local 
system. 


The value 36 indicates that, while the. user ID and password subfields are 
acceptable, the account subfield is not. For example, the specified user may 
not be authorized to use that billing account or the account may be ex- 
hausted. 
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data 


Up to 16 bytes of optional user data can be appended to the SYS call string 
(data) or sent from the I/O buffer (chnl + 0). 


Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 
Network operations have been terminated due to an internal error. Notify the 
system manager. 
5 CAN’T FIND FILE OR ACCOUNT 
The local link address (lla) given in bytes 5-6 does not correspond to any known 
logical link for the calling program. Either the lla is incorrect or the originating 
Connect Initiate request has been cancelled. In the latter case, a Disconnect or 
Link Abort Message has already been queued for this link. Since no ula was ever 
established, an lla field is available in the received Link Abort Message identify- 
ing the link. 
9 I/O CHANNEL NOT OPEN 
The channel specified in byte 11 is not open. The program must OPEN the 
channel buffer before using it for message operations. See Section 5.1.2. 
10 PROTECTION VIOLATION 
Some procedural error has occurred. Sending a Connect Reject Message for a 
logical link that is not waiting for confirmation or rejection will cause this error. 
For example, a Connect Reject Message for a link that is already established will 
return this error. 
18 ILLEGAL SYS() USAGE 
One of two possibilities: 
1. The calling program has not issued a Declare Receiver call. All DECnet func- 
tions require the caller to be a declared receiver. 
2. The reason code specified in bytes 23-24 was not 0, 34, or 36. 
31 ILLEGAL BYTE COUNT FOR I/O 
The offset and/or length fields passed in bytes 13-16 are inconsistent. The follow- 
ing relationships must be true: 
1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 
3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 1 and 16 for a Send Connect Reject 
Message call. 
32 NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store the user data portion of the 
Connect Reject Message. A retry may succeed. 


(continued on next page) 
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Cc 


ERR 
Value 


62 


66 


Example: 


Error Text and Meaning 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


In this example, a Connect Reject Message is sent to a remote program in 


response to a received Connect Initiate Message whose control information 
was returned to the target string B$. 


'EXAMPLE OF CONNECT REJECT 


! 
X$ = 


SYS(CHR$(G6%) + CHR$(22%) + CHRS(-4%) + CHRS(0%) 
+ MID(B$:5%+2%) + STRING$(347% 10%) 
+ "TOO LATE") 
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5.6.5 Send Network Data Message 


(DECnet) 


The Send Network Data Message call is used to transmit user data — a 
segment, as defined in Chapter 4 — over an established logical link. A flag can 
be set to indicate that the segment is also the end of a logical message. If the 
remote program requested flow control when the link was established, re- 
quests for data must be outstanding before this call can be issued. 


Data Passed: 


Bytes 


13-14 


15-16 


17-20 
21 


22-40 
41+ 


Value 


CHR$(6%) 
CHR$(22%) 
CHR§(-5%) 
CHR$(ula%) 
0% 
CHR$(chnl%) 


CHR$(0%) 
length% 


offset% 


0% 
CHR$(dmflgs%) 


0% 
data$ 


Data Returned: 


Description 


SYS call to FIP. 

Send/receive function code. 

Send Network Data Message subfunction code. 
User link address. 

Reserved - must be zero. 


Channel number of buffer containing the user message 
data, 1 to 12. If 0, this data is appended to the SYS call 
string. 

Reserved - must be zero. 


Length of data to be sent from the buffer (bytes). If 0, the 
number of bytes sent equals the buffer size minus offset. 
Ignored if chnl = 0. 


Offset (in bytes) from the beginning of the buffer where the 
user data begins. If 0, the data starts at the beginning of the 
buffer. Ignored if chnl = 0. 


Reserved - must be zero. 


Data message flags: rls% + eom% + bom%. 


rls = 128, link status data returned 


rls = 0, no link status data returned 
eom bom 
0 0 Middle segment of a message 


0 1 First segment of a message 
2 0 Last segment of a message 
2 1 Sole segment of a message 


Reserved - must be zero. 


User data, if appended to the string. 


If rls = 128, link status information is returned when this call is successfully 
completed. The data returned is identical in format to a received Link Service 
Message, as described in Section 5.7.7. 
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Discussion: 
ula 


The user link address (ula) is the link identifier (1 to 255) chosen by the 
calling program in its Connect Initiate Message or Connect Confirm Message 
sent during the connection sequence. 


choi 


The chnl parameter can be a number from 1 to 12, indicating which I/O buffer 
contains the user message data to be sent to the remote program. Or it can be 
0, indicating that this information is appended to the SYS call string. 


length 


The length parameter indicates how many bytes are to be sent from the I/O 
buffer. The maximum amount of data that can be transferred over this link is 
established by the remote program or remote NSP. It is passed on to the local 
program as a transmit maximum (the tmax parameter in a received Connect 
Initiate or Connect Confirm Message, Sections 5.7.2 and 5.7.3). Thus, length 
can be any value from one through tmax. 


If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the buffer. That is, the number of bytes sent is equal 
to the buffer size minus offset. This length is still limited by the transmit 
maximum, as described previously. 


The length parameter is ignored if chnl = 0; that is, if the user data is 
appended to the SYS call string. 


offset 


If an I/O buffer is used, the user message data can be offset from the beginning 
of the buffer. The size of the offset (in bytes) is indicated with this parameter. 
For example, if offset = 20, the user data begins in byte 21: 


byte 1 20 | 21 


whole buffer 
The offset field is ignored if chnl = 0. 


dmfigs 
The dmflgs field can be coded as the sum of three bit values: 
dmflgs% = rls% + eom% + bom% 


The low-order two bits of the dmflgs parameter (eom% + bom%) indicate 
whether the segment being sent in this Network Data Message is the first, 
last, middle, or sole segment of a logical message. If message flow control was 
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requested by the remote program when the link was established, NSP uses 
these two bits to regulate the transmission of logical messages as the remote 
program requests them. (See Chapter 4 for a full discussion of flow control.) 


eom bom 

0 0 Middle segment of a logical message 
0 1 First segment of a logical message 

2 0 Last segment of a logical message 

2 1 Sole segment of a logical message 


DECnet/E NSP uses the eom bit to count logical messages transmitted to the 
remote program. The bom bit is not used in maintaining the logical message 
request count but is simply passed to the remote system and program. 


NSP also uses the eom bit to determine whether it will permit a disconnect of 
the logical link. If a disconnect is requested but the last Network Data Mes- 
sage sent did not have the eom bit set, NSP assumes that the last message has 
not been completely sent and will not permit the disconnect. This is always 
done, irrespective of the flow control option selected by the remote program. 


Some DECnet implementations require that the eom flag be set to terminate 
an asynchronous I/O operation. Thus, when the remote program requests 
segment flow control or no flow control, the eom flag should always be set. 
Setting the flag in this case will not affect a remote DECnet/E node but is 
essential if the remote node is a DECnet node waiting to terminate asynchro- 
nous I/O. 


The sign bit of this byte (rls) is used to request that link status information be 
returned to the target string when the send call has successfully completed: 


rls = 128 Link status information is returned. 
rls = 0 No link status information is returned. 


If link status information is requested, it is returned in the same format as a 
received Link Service Message, as described in Section 5.7.7. 


data 


The user data to be transmitted to the remote program can be appended to 
the SYS call string (data) or sent from the I/O buffer (chnl + 0). In either case, 
the amount of data that can be transmitted is limited by the remote program 
or remote NSP. This transmit maximum is passed to the calling program in 
the tmax parameter in the received Connect Initiate or Connect Confirm 
Message (Section 5.7.2 or 5.7.3) for this logical link. 
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Possible Errors: 


ERR 
Value 


10 


18 


19 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


NO ROOM FOR USER ON DEVICE 


The Data Message transmit queue for this logical link is full. NSP is waiting for 
acknowledgment from the remote system for previously sent Network Data Mes- 
sages. No more can be sent until at least one of the outstanding messages in the 
transmit queue is acknowledged. This condition is temporary and no Link Service 
Message notification occurs when the condition clears. The program should sim- 
ply retry the send after a short (1 to 5 second) delay. (See Chapter 4 for a full 
discussion of flow control.) 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in byte 4 does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


1/0 CHANNEL NOT OPEN 


The I/O channel specified in byte 11 is not open. The program must OPEN the 
buffer before using it for message operations. See Section 5.1.2. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Network Data Message over a 
logical link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program has not issued a Declare Receiver call. All DECnet func- 
tions require the caller to be a declared receiver. 


2. The ula specified is zero. It must be within the range 1 to 255. 
DISK BLOCK IS INTERLOCKED 


Either the remote system has inhibited transmission on this link because of a 
backpressure condition or there are no outstanding requests for segments or logi- 
cal messages from the remote program (assuming it requested segment or message 
flow control for the link). 


The program will be notified with a Link Service Message when the condition 
clears, as described in Chapter 4. 


(continued on next page) 
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ERR 
Value 


31 


32 


62 


Example: 


Error Text and Meaning 


ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are inconsistent. The follow- 
ing relationships must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 1 and the transmit maximum 
(tmax) established by the remote program or system in its Connect Initiate or 
Connect Confirm Message for this logical link. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


The following Send Network Data call sends user data from a buffer. The null 
device is opened on channel 2 to obtain buffer space, the message data is 
loaded into the buffer using LSET, and the user data is sent. The use of 
JUNK$ at the beginning of the buffer illustrates the use of the buffer offset 


field. 


ULAZ = 
DMFLGS% 


14% 'USER LINK ADDRESS = 14 


1% + 2% 


'SOLE SEGMENT OF LOGICAL MESSAGE 


CHNL% = 


2 


va 'I1/0 BUFFER ON CHANNEL 2 


OPEN "NL:" AS FILE CHNL%+ RECORDSIZE 100% 
FIELD CHNL%+ 10% AS JUNK$» 90% AS TEXT$ 


MSGS = 
LENGTH% 
OFFSET% 


ou 


:"THIS MESSAGE WAS SENT FROM A BUFFER" 


LEN(MSG$) 
LEN( JUNK$) 


LSET TEXT = MSGS 


'EXAMPLE OF SEND NETWORK DATA MESSAGE 


X$ = SYS(CHR$(G6%) + CHR$(22%) + CHR$(-5%) + CHRS(ULAZ) 


+ 
% 
+ 
+ 


STRING$(6%+0%) + CHRS(CHNL%Z) + CHR$(0%) 
CHR$(LENGTH%Z) + CHRS(SWAP%(LENGTH%) ) 
CHRS(OFFSET%) + CHRS(SWAPZ(OFFSET%) ) 
STRING$(4%;0%) + CHR#(DMFLGS%) ) 
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5.6.6 Send Interrupt Message (DECnet) 


The Send Interrupt Message call transmits an Interrupt Message to a remote 
program over an established logical link. All DECnet systems are designed to 
deliver Interrupt Messages ahead of other messages. If the remote system is a 
DECnet/E system, the Interrupt Message will be placed at the head of the 
pending message queue, behind the first message (since it can already be 
partly received) and behind any other pending Interrupt Messages queued for 
the program. Interrupt Messages are subject to flow control, as described in 
Chapter 4. 


Data Passed: 


Bytes Value Description 

1 CHR$(6%) SYS call to FIP. 

2 CHR$(22%) Send/receive function code. 

38 CHR$(-6%) Send Network Interrupt Message subfunction code. 
4 CHR$(ula%) User link address. 

5-10 0% Reserved - must be zero. 

11 CHR$(chnl%) Channel number of buffer containing the user message 
data, 1 to 12. If 0, this data is to be appended to the SYS 
call string. 

12 CHR$(0%) Reserved - must be zero. 

13-14 length% Length, in bytes of data to be sent from the buffer, 1 to 16. 
If 0, the number of bytes sent equals the buffer size minus 
offset. Ignored if chnl = 0. 

15-16 offset% Offset (in bytes) from the beginning of the buffer where the 
user data begins. If 0, the data starts at the beginning of the 
buffer. Ignored if chnil = 0. 

17-20 0% Reserved - must be zero if passed. 

21 inflgs% Interrupt flags. inflgs% = rls% 
rls = 128, link status data returned. 
rls = 0, no link status data returned. 

22-40 0% Reserved - must be zero if passed. 

41-56 data$ Optional user data, if appended to the string. Maximum of 


16 bytes. Ignored if chnil + 0. 


Data Returned: 
If rls = 128, link status information is returned when this call is successfully 


completed. The data returned is identical to a received Link Service Message, 
as described in Section 5.7.7. 
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Discussion: 
ula 


The user link address (ula) is the link identifier (1 to 255) chosen by the 
calling program in its Connect Initiate Message or Connect Confirm Message 
sent during the connection sequence for this logical link. 


chnl 


The chnl parameter can be a number from 1 to 12, indicating which I/O buffer 
contains the user data to be sent to the remote program. Or it can be 0, 
indicating that this information is appended to the SYS call string. 


length 


The length parameter indicates how many bytes are to be sent from the I/O 
buffer. Acceptable values range from 1 through 16. This field is ignored if chnl 


' =0. 


If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the channel. That is, the number of bytes sent is 
equal to the buffer size minus offset. This length is also limited to 1 to 16 
bytes. 


offset 


If an I/O buffer is used, the user data, if any, can be offset from the beginning 
of the buffer. The size of the offset (in bytes) is indicated with this parameter. 
For example, if offset = 20, the user data begins in byte 21: 


byte 1 20 } 21 


whole buffer 
The offset field is ignored if chnl = 0. 
inflgs 


The inflgs parameter indicates whether link status information is to be re- 
turned to the target string when this call is successfully completed. This field 
should be coded as follows: 


inflgs% = rls% 
where 


rls = 128 Link status information is returned. 
rls = 0 No link status information is returned. 


If link status is requested, it is returned in the same format as a received Link 
Service Message (Section 5.7.7). 
data 


Up to 16 bytes of optional user data can be appended to the SYS call string 
(data) or sent from the I/O buffer (chnl + 0). 
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Possible Errors: 


ERR 
Value 


10 


18 


19 


31 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


NO ROOM FOR USER ON DEVICE 


The Interrupt/Link Service transmit queue for this logical link is full. NSP is 
waiting for acknowledgment from the remote system for previously sent Interrupt 
or Link Service Messages. No Interrupt or Link Service Message can be sent until 
at least one of the outstanding messages in the transmit queue is acknowledged. 
This condition is temporary and no Link Service Message notification occurs 
when the condition clears. The program should simply retry the send after a short 
delay of from 1 to 5 seconds. (See Chapter 4 for a full discussion of flow control.) 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in byte 4 does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


1/0 CHANNEL NOT OPEN 


The channel specified in byte 11 is not open. The program must OPEN the I/O 
buffer before using it for message operations. See Section 5.1.2. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending an Interrupt Message over a logical 
link that has not yet been confirmed will cause this error to occur. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program has not issued a Declare Receiver call. All DECnet func- 
tions require the caller to be a declared receiver. 


2. The ula specified was zero. It must be within the range 1 to 255. 
DISK BLOCK IS INTERLOCKED 


The remote NSP has prohibited transmission of Interrupt Messages over this 
logical link according to its rules for Interrupt Message flow control. (See Chapter 
4 for a full discussion of flow control.) A Link Service Message will be delivered to 
the program when the condition clears, as described in Chapter 4. 


ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are inconsistent. The follow- 
ing relationships must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 1 and 16 for an Interrupt Message. 


(continued on next page) 
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ERR 
Value 


32 


62 


66 


Example: 


Error Text and Meaning 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP 
has been enabled by the system manager. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


The following example illustrates a Send Interrupt Message call. The user 
data, START PHASE 2, is passed to a remote program over logical link 170. 
(The remote program would have to be coded to recognize this message and 
take appropriate action.) 


ULA% 
| 


170% 


'EXAMPLE OF SEND INTERRUPT CALL 
l 


KS = 


SYS(CHR$(6%) + CHR$(22%) + CHR#(-6%) + CHRS(ULAZ) 
+STRING$(36%+0%) + "START PHASE 2") 
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5.6.7 Send Link Service Message (DECnet) 


The Send Link Service Message call is used in three ways: (1) to request data 
from a remote program over a flow-controlled logical link (Chapter 4); (2) to 
reenable incoming Interrupt Messages over a logical link (Chapter 4); or (3) to 
obtain status information for the link. No user data is allowed with a Link 
Service Message. 


Data Passed: 


Bytes Value Description 

1 CHR$(6%) SYS call to FIP. 

2 CHR$(22%) Send/receive function code. 

3 CHR$(-7%) Send Link Service Message subfunction code. 
4 CHR$(ula%) User link address. 

5-12 0% Reserved — must be zero. 
13-16 0% Ignored. 
17-20 0% Reserved - must be zero. 

21 CHR$(Isflgs%) Link service flags. Isflgs% = rls% + opr%. 


opr% indicates the purpose of the call: 


opr =0 Request data from remote program over flow- 
controlled link 
= 1 Reenable Interrupt Messages 
=2 Obtain status information 


If rls = 128, link status information is returned when opr = 0 
or 1. If rls = 0, no link status information is returned when 


opr = O or 1. 
22 CHR$(0%) Reserved - must be zero. 
23 CHR$(drent%) Data request count. Increment for logical message or 


counter. Must be positive and not cause counter to exceed 
127. Ignored when opr + 0. 


24 CHR§(ircnt%) Interrupt request count. Must equal 1 when opr = 1. Ig- 
nored otherwise. 
25-40 0% Reserved - must be zero if passed. 


Data Returned: 


If opr = 2, or if rls = 128 when opr = 0 or 1, link status information is returned 
when this call completes successfully. The data returned is identical to a 
received Link Service Message, as described in Section 5.7.7. 


Discussion: 


ula 


The user link address (ula) is the link identifier (1 to 255) chosen by the 
calling program in its Connect Initiate Message or Connect Confirm Message 
sent during the connection sequence for this logical link. 
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Isflgs 


The link service flags byte is coded as the sum of two values: Isflgs% = rls% + 
opr%. The low-order two bits (opr) indicate the purpose of the call. 


opr =0 Indicates the call is requesting segments or logical messages from 
the remote program. In this case, the drcnt parameter is inter- 
preted as the number of segments or logical messages being re- 
quested. This form of the call can be used only when the calling 
program requested segment or message flow control in its Connect 
Initiate or Connect Confirm Message for this logical link. If no flow 
control was requested, a Send Link Service call with opr = 0 will 
fail with ERR = 18. 


=1 Indicates the call is to reenable incoming Interrupt Messages for 
this link. In this case, the ircnt parameter is interpreted as the 
number of Interrupt Messages allowed (always 1). 


=2 Indicates the call is to obtain status information only. In this case, 
the drent and ircnt parameters are ignored. 


The sign bit of this byte (ris) can be used when opr = 0 or 1 to request that link 
status information be returned to the SYS call string when the call has com- 
pleted successfully. 


rls = 128 Link status information is returned. 
rls = 0 No link status information is returned. 


Link status information is always returned when opr = 2. If status information 
is requested, it is returned in the same format as a received Link Service 
Message (Section 5.7.7). 


drent 


The data request count (drcnt) is meaningful only when opr = 0 and indicates 
the maximum number of segments or logical messages being requested from 
the remote program. Depending on the flow control option in effect for the 
logical link, the value is interpretted as either a segment request count (seg- 
ment flow control) or as a logical message request count (message flow con- 
trol). In either case, it is an incremental count, added to the counter of 
outstanding requests for segments or logical messages kept by the remote and 
local NSP (see Chapter 4). An error is returned if the drcnt given increases the 
counter to more than 127. 


ircnt 


The interrupt request count (ircnt) is meaningful only when opr = 1. It indi- 
cates the number of Interrupt Messages being requested. DECnet/E allows 
only one interrupt request outstanding for a logical link at any given time. 
Hence, ircnt must always be 1 when opr = 1 and has the effect of reenabling 
incoming interrupts on the logical link. (Remember that interrupts can be 
reenabled only when the previous Interrupt Message for this logical link, if 
any, has been received from the pending message queue. If it has not, the call 
will fail with ERR = 19.) 
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Possible Errors: 


ERR 
Value 


10 


18 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


NO ROOM FOR USER ON DEVICE 


The Interrupt/Link Service transmit queue for this logical link is full. NSP is 
waiting for acknowledgment from the remote system for previously sent Interrupt 
or Link Service Messages. No Interrupt or Link Service Messages can be sent 
until at least one of the outstanding messages in the transmit queue is acknowl- 
edged. This condition is temporary and will not cause a Link Service Message to 
be queued when the condition clears. The program should simply retry the send 
after a short (1 to 5 second) delay. (See Chapter 4 for a full discussion of flow 
control.) 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in byte 4 does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


1/0 CHANNEL NOT OPEN 


Since the Link Service Message does not provide for transmitting user message 
data, the byte used for channel number in all other system calls (byte 11) should 
always be zero. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Link Service Message over a 
logical link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of several possibilities: 


1. The calling program has not issued a Declare Receiver call. All DECnet func- 
tions require the caller to be a declared receiver. 


2. The opr value in byte 21 is not 0, 1, or 2. 


3. The opr value is 0, but the calling program did not request flow control for the 
logical link in its Connect Initiate or Connect Confirm Message. 


4. The data request count (drcnt) value given increased the count of outstanding 
requests to a value greater than 127. 


5. The opr value is 1, indicating an Interrupt Message is being requested, but the 
ircnt parameter is not equal to 1. 


6. The opr value is 1, but the outstanding requests counter for interrupts is 
already equal to 1. 


7. The ula given is 0. It must be within the range 1 to 255. 


(continued on next page) 
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5-50 


ERR 
Value 


19 


31 


32 


62 


Example: 


Error Text and Meaning 


DISK BLOCK IS INTERLOCKED 


The opr value is 1, indicating a request for an Interrupt Message, but there is 
already an Interrupt Message queued for this logical link. (See Chapter 4 for 
details on flow control.) 


ILLEGAL BYTE COUNT FOR I/O 


This error can occur if byte 11 (the chni number in all other system calls) is 
nonzero. In this case, the system attempts its consistency checking for length and 
offset fields in bytes 13-16 and has found them to be inconsistent. Since no 
message data can be transmitted with a Link Status Message, byte 11 should be 
zero. 


NO BUFFER SPACE AVAILABLE 
System buffers are unavailable to store this message. A later try may succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet system calls cannot be executed until 
NSP is enabled by the system manager. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


The following example sends a Link Service Message to request five segments 
from the remote program over logical link 12. (Assume that segment flow 
control was requested by the program in its Connect Initiate or Connect 
Confirm Message that established the logical link.) 


DRCNT% 
| 


'EXAMPLE OF SEND LINK SERVICE MESSAGE CALL 
| 


X$ = SYS(CHR$(6%) + CHR$(22%) + CHRS(-7%) + CHRS(ULAY%) 


+STRING$ (16% 50%)+CHR$(LSFLGS%)+CHRS$(0%) 
+CHRS(DRCNT%) ) 
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5.6.8 Send Disconnect Message (DECnet) 


This call is used to terminate an established logical link. Messages in the 
pending message queue will remain. No more messages can be sent over the 
link, however. The user link address is freed and can be used for another 
logical link. If the last Network Data Message sent did not have the end-of- 
message flag set, or if any Network Data, Interrupt, or Link Service Messages 
are still waiting for acknowledgment in the transmit queues for this logical 
link, this call will fail with an error. 


Successful transmission of a Disconnect Message assures the sender that the 
remote system has received and acknowledged all Network Data, Interrupt, 
and Link Service Messages previously sent over the link. It does not, however, 
guarantee that the receiving program has processed the messages. The 
Disconnect Message is useful in ‘master-slave’ communication where the 
master program only transmits data and the slave program only receives data 
(see Section 3.13). Otherwise, the Disconnect Message provides no particular 
advantage over a Link Abort Message (Section 5.6.9) in terminating a logical 
link. 


Up to 16 bytes of user data can be sent with the Disconnect Message. 


Data Passed: 


Bytes Value Description 
1 CHR$(6%) SYS call to FIP. 
2 CHR$(22%) Send/receive function code. 
3 CHR$(-8%) Send Disconnect Message subfunction code. 
4 CHR$(ula%) User link address. 
5-10 0% Reserved - must be zero. 
11 CHR$(chnl%) Channel number of buffer containing the (optional) mes- 
sage data, 1 to 12. If 0, data is appended to the string. 
12 CHR$(0%) Reserved — must be zero. 
13-14 length% Length, in bytes, of data to be sent from the buffer, 1 to 16. 
If 0, the number of bytes sent equals buffer size minus 
offset. Ignored if chnl = 0. 
15-16 offset % Offset (in bytes) from the beginning of the buffer where the 
user data begins. If 0, the data starts at the beginning of the 
buffer. Ignored if chnl = 0. 
17-40 0% Reserved - must be zero. 
41-56 data$ Optional user data, if appended to the string. Maximum of 


Data Returned: 


16 bytes. Ignored if chnil + 0. 


No meaningful data is returned. 
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5-52 


Discussion: 
ula 


The user link address (ula) is the number (1 to 255) that was established by 
the calling program in its Connect Initiate or Connect Confirm Message sent 
during the connection sequence for this logical link. 


choi 


The chnl parameter can be a number from 1 to 12, indicating which I/O buffer 
contains the user data to be sent to the remote program. Or it can be 0, 
indicating that this information is appended to the SYS call string. 


length 


The length parameter indicates how many bytes are to be sent from the I/O 
buffer. Acceptable values range from 1 through 16. This field is ignored if chnl 
= 0. 

If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the channel. That is, the number of bytes sent is 
equal to the buffer size minus offset. This length must also fall in the range of 
1 to 16 bytes. 


offset 


If an I/O buffer is used, the user data, if any, can be offset from the beginning 
of the buffer. The size of the offset (in bytes) is indicated with this parameter. 
For example, if offset = 20, the user data begins in byte 21: 


byte 1 





The offset field is ignored if chnl = 0. 

data 

Up to 16 bytes of optional message data can be appended to the SYS call 
string (data) or sent from the channel buffer (chnl + 0). 


Possible Errors: 


ERR 
Value Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 
Network operations have been terminated due to an internal error. Notify the 
system manager. 
4 NO ROOM FOR USER ON DEVICE 


There are outstanding unacknowledged messages on either the Data Message 
transmit queue or the Interrupt/Link Service transmit queue. All messages previ- 
ously sent over the logical link must be acknowledged before the Disconnect 
Message can be sent. (If an immediate unconditional termination of the logical 
link is desired, a Link Abort Message should be sent.) 

(continued on next page) 
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10 


18 


19 


31 


32 


62 


Error Text and Meaning 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in byte 4 does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


1/0 CHANNEL NOT OPEN 


The chnl specified in byte 11 is not open. The program must OPEN the channel 
buffer before using it for message operations. See Section 5.1.2. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Disconnect Message over a logical 
link that has not been confirmed will cause this error to occur. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program has not issued a Declare Receiver call. All DECnet func- 
tions require the caller to be a declared receiver. 


2. The ula specified is 0. It must be within the range 1 to 255. 


DISK BLOCK IS INTERLOCKED 


The last segment sent by the local program over this logical link did not have the 
eom flag set. NSP will not permit a logical link to be disconnected unless all 
messages have been completely sent. (Note that this test of the eom flag is done 
irregardless of the flow control option chosen by the remote program.) 


ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are inconsistent. The follow- 
ing must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 1 and 16 for a Disconnect Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store the optional message data 
portion of the Disconnect Message. A later retry may succeed. (A request to send a 
Disconnect Message will never fail for this reason if no user data is passed.) 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 
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Example: 


The following example disconnects logical link 230 and includes user data 
explaining the reason for the disconnect. (The remote program would have to 
be coded to recognize this message and take appropriate action.) 


! 
'EXAMPLE OF SEND DISCONNECT 
| 


X$ = SYS(CHR$(6%) + CHR$(22%) + CHR$(-8%) + CHRS(230%) + 
STRING$(36%.0%) + “END-OF-FILE") 
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5.6.9 Send Link Abort Message 


This call is used to terminate a logical link immediately. Unlike the Discon- 
nect Message, no attempt is made to ensure that all messages previously sent 
over this logical link have been received by the remote system. If there are still 
messages in the transmit queues waiting for acknowledgment from the remote 
NSP, they will be discarded. They may or may not have been received by the 
remote system (see Section 3.14). 


Up to 16 bytes of user data can be specified in the message. If the Link Abort 
Message is issued for an established logical link, the remote system is notified 
that the link has been broken and the user data is delivered to the remote 
program. If the Link Abort Message is issued for a logical link awaiting confir- 
mation from the remote program, the user data does not reach the remote 
program (see Section 3.14). 


Data Passed: 


Bytes Value Description 
1 CHR$(6%) SYS call to FIP. 
2 CHR$(22%) Send/receive subfunction code. 
3 CHR$(-9%) Send Link Abort Message subfunction code. 
4 CHR$(ula%) User link address. 
5-10 0% Reserved - must be zero. 
11 chnl% Channel number of buffer containing the (optional) user 
data, 1 to 12. If 0, this data is to be appended to the string. 
12 0% Reserved - must be zero. 
13-14 length% Length, in bytes, of data to be sent from the buffer, 1 to 16. 
If 0, the length is equal to the buffer size minus offset. 
Ignored if channel = 0. 
15-16 offset% Offset (in bytes) from the beginning of the buffer where the 
user data begins. If 0, the data starts at the beginning of the 
buffer. Ignored if chnl = 0. 
17-40 0% Reserved - must be zero. 
41+ data$ Optional user data, if appended to the string; maximum of 


Data Returned: 


16 bytes. Ignored if chnl + 0. 


No meaningful data is returned. 


Discussion: 


ula 


The user link address (ula) is the number (1 to 255) that was established by 
the calling program in its Connect Initiate or Connect Confirm Message sent 
during the connection sequence for this logical link. 
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chnl 


The chnl parameter can be a number from 1 to 12, indicating which I/O buffer >) 
contains the user data to be sent to the remote program. Or it can be 0, to 
indicate that this information is appended to the SYS call string. 


length 


The length parameter indicates how many bytes are to be sent from the I/O 
buffer. Acceptable values range from 1 through 16. Or, it can be zero. 


If length = 0, the number of bytes sent is determined from the offset parame- 
ter and the size of the entire buffer, as defined by the RECORDSIZE option in 
the OPEN statement for the buffer. That is, the number of bytes sent is equal 
to the buffer size minus offset. This length must also fall in the range of from 1 
to 16 bytes. 


offset 


If a channel buffer is used, the user message data, if any, can be offset from ; 
the beginning of the buffer. The size of the offset (in bytes) is indicated with 2.) 
this parameter. For example, if offset = 20, the user data begins in byte 21: 


byte 1 20} 21 


whole buffer 
The offset field is ignored if chnl = 0. 2) 
data 


Up to 16 bytes of optional user data can be appended to the SYS call string 
(data) or sent from the channel buffer (chnil + 0). This data will not reach the 
remote program if the Link Abort Message is issued for a link awaiting confir- 
mation from the remote program (see Section 3.14). 


Possible Errors: 


cnn J 


Value Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


5 CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in byte 4 does not correspond to any known 
logical link for the calling program. Hither the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


(continued on next page) 
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Value Error Text and Meaning 


9 1/0 CHANNEL NOT OPEN 


The channel specified in byte 11 is not open. The program must OPEN the I/O 
buffer before using it for message operations. See Section 5.1.2. 


18 ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program has not issued a Declare Receiver call. All DECnet func- 
tions require the caller to be a declared receiver. 


2. The ula specified is 0. It must be within the range 1 to 255. 
31 ILLEGAL BYTE COUNT FOR I/O 


The offset and/or length fields passed in bytes 13-16 are inconsistent. The follow- 
ing must be true: 


1. The offset must be less than the buffer size. 
2. The length must be less than or equal to the buffer size minus the offset. 


3. The number of bytes to be sent (as defined by length, or if length = 0, by 
buffer size minus offset) must be between 1 and 16 for a Link Abort Message. 


32 NO BUFFER SPACE AVAILABLE 
System buffers are not currently available to store this message. A later retry may 
succeed. 

62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until NSP is 
enabled by the system manager. 


66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


Example: 
The following example aborts logical link 31. 


! 
'EXAMPLE OF SEND LINK ABORT MESSAGE 
! 


K$ = SYS(CHRS$(G6%) + CHR$(22%) + CHR#(-9%) + CHR$(31%)) 
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5.7 Receive System Call 


The Receive call is used to retrieve a message from the calling program’s 
pending message queue. It returns control parameters to the target string and 
user data, if any, to an I/O buffer specified in the call. The Connect Data 
Block for Connect Initiate Messages is also delivered to the I/O buffer. The 
user data can be retrieved all at once or in portions, and portions can be 
discarded. 


A Receive call can be selected to get (1) the first message in the queue, (2) the 
first message in the queue from either a network or a local sender, or (3) the 
first message in the queue for a particular logical link. A “sleep” flag and 
associated timer can be set to indicate that the calling program is to wait if 
there are no appropriate messages pending in the queue. Otherwise, if there 
are no appropriate messages pending, the Receive call terminates with an 
error (ERR = 5). 


Data Passed: 


Bytes Value Description 
1 CHR$(6%) SYS call to FIP. 

2 CHR(22%) Send/receive function code. 

3 CHR$(2%) Receive subfunction code. 

4 CHR3$(rmod%) Receive modifier: n%+1%+t%+s% 
s Sleep if no messages? 0 = no, 1 = yes 
t Truncate excess data? 0 = no, 2 = yes 
| Select local messages? 0 = no, 4 = yes 


n Select network messages? 0 = no, 8 = yes 
(n ignored if | = 4) 


If | and n = 0, receive from overall queue. 
5 CHR$(sndr%) Sender selection. Ignored if both / and n = 0. 


If |= 4, sndr = 2 x job number to select a particular local 
sender. 


If n = 8, sndr = user link address to select a particular 
logical link. 


6 CHR$(qual%) Normally zero. A special case is described in the discussion 
below. 
7-10 0% Ignored. 
11 CHR$(chnl%) Channel number of buffer to which data is to be delivered 


(1 to 12). If 0, all data is to be saved or discarded, depend- 
ing on value of t in byte 4. 


12 CHR$(0%) Reserved - must be zero. 


13-14 length% Maximum length (in bytes) of data to be returned to the 
buffer on this Receive call. Ignored if chni = 0. 


(continued on next page) 
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Bytes Value Description 


15-16 offset % Offset (in bytes) from beginning of buffer where data is to 


begin. If 0, data is stored starting at the beginning of the 
buffer. Ignored if chnl = 0. 


17-20 0% Reserved - must be zero. 
21-26 0% Ignored. 
27-28 slptime% Sleep time, in seconds. If 0, indicates indefinite sleep (see 


Discussion). Ignored if s in byte 4 = 0. 


29-40 0% Reserved - must be zero if passed. 


Data Returned: 


Formats for the various types of messages that can be returned on a Receive 
call are described in Sections 5.7.1 - 5.7.9. 


Discussion: 


rmod 


The receive modifier (rmod) consists of four flags: s% + t% + 1% + n%. 


s 


The sleep flag (s) defines what is to be done if there is no appropriate 
message in the queue for the Receive call to deliver — that is, a message of 
the type requested with the /, n, sndr, and qual arguments. If s = 1, the 
program will “sleep,” or suspend execution, until something happens. The 
slptime parameter regulates the time that the program will sleep. 


If the s flag is set to 0, the program will not sleep if there are no appropri- 
ate pending messages. The call terminates immediately with ERR = 5. 


The truncate flag (t) is set to 2 to discard any excess data that will not fit 
in the I/O buffer specified in this call. Information could be left over 
because (1) the chnl parameter is set to 0, or (2) the length parameter (or 
if length = 0, the buffer size minus offset) is less than the actual amount of 
data in the message. 


A 0 value for t indicates that all excess data is to be kept for retrieval on 
later Receive calls. 


The local sender flag (1) is set to 4 to select a message from a local sender. 
The selection can be further qualified by the sndr and qual parameters. 


If ! = 0, local selection is not requested. If both | and n = 0, the first 
message in the queue is returned. 


The network sender flag (n) is set to 8 to select a message from a network 
sender. The selection can be further qualified by the sndr and qual param- 
eters. 


If n = 0, network selection is not requested. If both / and n = 0, the first 
message pending in the queue is returned. If | = 4, and n = 8, local 
selection prevails. 
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sndr 


The sender selection parameter (sndr) is used to select a particular local 
sender or a particular logical link for this Receive call. 


If | = 4 (local selection) and sndr is nonzero, sndr is interpreted as a job 
number times two. The first message on the queue from that particular local 
job is retrieved. 


If 1 = 0 and n = 8 (network selection), a nonzero value for sndr is interpreted as 
a user link address. The first message on the queue from that logical link is 
delivered. 


If sndr = 0 when either | = 4 or n = 8, the qual parameter has special meaning. 
The sndr and qual parameters are ignored if both / and n are zero. 

qual 

The sender selection qualifier is normally zero for user applications. 


If 1 = 4 (local selection) and sndr = 0, then any nonzero value for qual is a 
special-case Receive call, requesting a message from the system (job number 
0). This special case is used by the RSTS/E utility program ERRCPY which 
processes messages from the monitor error logging routines. 


The qual parameter is ignored if both / and n = 0, or if sndr + 0. 


Table 5-4 summarizes the relationships between the selection bits / and n, 
and the sndr and qual parameters. 


Table 5-4: Sender Selection Summary 


rmod 

n ot sndr qual Result 

0 0 n/a n/a The sndr and qual values are ignored. The Receive 
call returns the first message in the pending message 
queue. 

n/a 4 0 0 Selects the first Local Data Message in the queue. 

0 nonzero Selects job 0. This combination is used by the error 
logging programs to select messages from monitor er- 
ror logging routines. 

nonzero n/a Selects Local Data Messages by job number. sndr is 
interpreted as a job number times 2. Only messages 
from that job will be delivered on this Receive call. 

8 0 0 n/a Selects the first network message (anything other 


than a Local Data Message) in the queue. 


nonzero n/a Selects network messages from a particular logical 
link. sndr is interpreted as a user link address. Only 
network messages from the designated logical link 
will be delivered on this Receive call. 
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choi 


The chnl parameter can be a number from 1 to 12, indicating the buffer to 
which the data (if any) is to be delivered. Or chni can be 0, indicating that all 
of this information is to be (1) saved for retrieval in a later Receive call (if ¢ in 
byte 4 = 0), or (2) discarded (t = 2). 


length 


The length field is ignored if chnl = 0. Otherwise, length indicates the maxi- 
mum number of bytes of information to be delivered to the 1/O buffer on this 
Receive call. If nonzero, this value must be less than or equal to the buffer size 
minus offset. 


If length = 0, the maximum number of bytes to be delivered to the buffer is 
equal to the buffer size minus offset. (The buffer size is defined by the RE- 
CORDSIZE option in the OPEN statement that allocated the buffer.) 


If a program has limited buffer space, the length value can be used to process 
a large segment in small pieces. If truncation is not requested (t in byte 4 = 0) 
and the amount of data in the message is greater than the amount indicated 
by length, then only the amount indicated by length will be returned. The rest 
will be saved for retrieval with later Receive calls. 


The usual sequence in this case is to issue Receive calls until the number of 
bytes remaining in the pending message goes to zero. This point can be deter- 
mined from the control information returned to the target string on a Receive 
call. Bytes 9-10 returned in the string indicate the number of bytes remaining 
in the pending message. The number of bytes actually returned to the buffer 
is given in bytes 13-14 of the returned string. 


offset 


Received data can be offset from the beginning of the buffer. The size of the 
offset (in bytes) is indicated by this parameter. For example, if offset = 20, the 
data will be delivered beginning at byte 21: 


byte 1 20 | 21 


whole buffer 


The offset must be in the range 0 through buffer size minus 1. (The buffer size 
is defined by the RECORDSIZE option in the OPEN statement that allocated 
the buffer.) 

slptime 


The slptime parameter is significant only when the s flag of rmod = 1. In that 
case, slptime defines the length of time, in seconds, that a program is to sleep 
when no appropriate message is pending in the queue. The program will sleep 
until: 


1. The sleep timer (slptime) expires. 


2. Any new message is placed in the queue (not just an appropriate one). 
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3. A delimiter is typed on a terminal opened by, or assigned to, this job. 
4, Log-ins are disabled. (This could occur if the system is being shut down.) 


5. A state change occurs on a pseudo-keyboard assigned to the job. (The job 
has printed output for the controlling job to read or has entered an input 
wait state.) 


6. The job itself has opened the XM: (DMC11 driver) and a message is 
received for the job. 


In all cases, the program is awakened with an error (ERR = 5) but is not 
passed a message. To obtain a pending message, the program must execute 
another Receive call. Since the program can be awakened by any of the 
conditions listed previously, a check for pending messages can be made by 
issuing a Receive call without a sleep. A check for terminal input can be made 
by executing a terminal input operation (GET) using the RECORD 8192% 
modifier for immediate return. (See the RST'S/E Programming Manual.) 


Possible Errors: 


ERR 

Value Error Text and Meaning 

5 CAN’T FIND FILE OR ACCOUNT 
For a Receive call without sleep (s in byte 4 = 0), this error indicates that no 
appropriate messages are pending. For a Receive call with sleep (s = 1), this error 
is returned when the program is awakened from the sleep. The program must 
execute another Receive call to retrieve any pending messages. (See the previous 
discussion of the s flag for further details.) 

9 I/O CHANNEL NOT OPEN 
A Receive call was issued and the channel specified in byte 11 of the data passed 
was not open. The program must OPEN the channel before using it for message 
operations. See Section 5.1.2. 

18 ILLEGAL SYS() USAGE 
No Receiver ID Block exists for the calling program. Before any Receive call can 
succeed, a Declare Receiver call must be executed. 

31 ILLEGAL BYTE COUNT FOR I/O 


The offset and length fields passed in bytes 13-16 are invalid. The following 
relationships must be true for a Receive call: 


1. The offset must be less than the buffer size. 


2. The length must be less than or equal to the buffer size minus offset. 
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Example: 


In the following example, a Receive call is issued for the first message in the 
queue. The sleep bit is set and the timer is set to three seconds. The truncate 
bit is 0, as is the channel, so all the information that is available is saved for 
another Receive call. (The program will examine the third byte of the re- 
turned target string to see what type of message is available and GOTO an 
appropriate section of code depending on its value.) 


RMOD% = 1% 'SLEEP IF NO MESSAGES 
SLPTIME% =3% !SLEEP MAX. OF 3 SECONDS 
CHNL% = 0% ISAYVE ALL DATA FOR NEXT RECEIVE 


! 

'EXAMPLE OF RECEIVE CALL 

! 

X$ = SYS(CHR$(G%) + CHR$(22%) + CHRS(2%) + CHRS(RMODZ) 
+ STRINGS$(G6%Z 10%) 
+ CHRS(CHNL%Z) + STRING$(15% 150%) 
+ CHRS(SLPTIMEZ) + CHRS(SWAPZ(SLPTIME%))) 
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5.7.1 Format of Received Local Data Message 


The format of the information returned to the target string for a Local Data 
Message is described below. Up to 512 bytes of user data can be delivered to 
the I/O buffer specified in the Receive call. 


Bytes 


1-2 


Value 


CHR$(-1%) 
CHR$(jobx2%) 
ppn% 


remainder% 


length% 


param$ 


Description 


Not meaningful - should be ignored. 
Local Data Message subfunction code. 
Two times the job number of the local sender. 


Project-programmer number of the local sender. Byte 5 = 
programmer number, byte 6 = project number. 


Not meaningful - should be ignored. 


Number of bytes of user data not delivered to I/O buffer. 
This data has been either discarded or saved for a later 
Receive call, depending on how the t flag was set. 


Not meaningful - should be ignored. 


Length (in bytes) of information transferred to the I/O 
buffer on this Receive call. 


Not meaningful - should be ignored. 


The data passed as parameters by the sender of this mes- 
sage. The system pads any unused bytes with binary zeros 
to a length of 20 bytes. 
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5.7.2 Format of Received Connect Initiate Message 


The format of the information returned to the target string is described below. 
A 120-byte Connect Data Block and up to 16 bytes of user data are also 
returned to the I/O buffer specified in the Receive call. The format of a 
received Connect Data Block is shown in Figure 5-2 and described in detail in 


Table 5-5. 


Bytes 


1-2 
3 
4 
5-6 


7-8 
9-10 


11-12 
13-14 


15-22 
23 


24 
25-26 


27-28 


29-40 


Value 


CHR$(-2%) 


lla% 


remainder% 


length% 


CHR$(rimod%) 


rmax% 


tmax% 


Description 


Not meaningful - should be ignored. 
Connect Initiate Message subfunction code. 
Not meaningful - should be ignored. 


Local link address. Identifies the link for the local pro- 
gram’s subsequent Connect Confirm or Connect Reject 
Message. 


Not meaningful - should be ignored. 


Number of bytes of data not returned to the I/O buffer. 
This data has been either discarded or saved for a later 
Receive call, depending on how the t¢ flag was set. 


Not meaningful - should be ignored. 


Length (in bytes) of data transferred to the I/O buffer on 
this Receive call. 


Not meaningful - should be ignored. 


Remote link modifier. Indicates the flow control in effect for 
the remote program. The two low-order two bits should be 
masked and interpretted as follows: 


flow% = rlmod% AND 3% 


If flow 0, no flow control 
1, segment flow control 


2, message flow control 


tou dl 


Not meaningful - should be ignored. 


Receive maximum, in bytes. The maximum amount of user 
data that will be transmitted to the local program in one 
Network Data Message over this link. The rmax value is 
supplied by the local NSP and is calculated from the size of 
the receive buffers it allocates. The maximum size of the 
receive buffers is set for NSP by Network Management. 
The local program can further limit the amount of user 
data to be received by specifying a smaller rmax in the 
Connect Confirm Message that accepts this request for a 
connection. (See Section 5.6.3.) 


Transmit maximum, in bytes. The maximum amount of 
user data that can be transmitted by the local program in 
one Network Data Message over this link. This limit has 
been imposed by either the remote program or the remote 
NSP. The local NSP enforces this limit for all Network 
Data Messages sent by the local program on this link. 


Not meaningful - should be ignored. 
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Figure 5-2: Format of Received Connect Data Block 


Table 5-5: Format of Received Connect Data Block 


Bytes Content 


1-6 Remote Node. 1 to 6 uppercase, alphanumeric characters giving the name of 
the remote node from which the Connect Initiate Message was received. The 
name will contain at least one alphabetic character. Node names shorter than 
six characters are left-justified and padded to six characters with spaces. 


7-26 Remote Program. Identifies the remote program that sent the Connect Initi- 
ate Message as either an object type (general function) or a specific entity 
(program, task, or process). This identification is given in one of three formats. 


Format 0 
The remote program is identified by object type code alone. The fields are: 
Bytes Content 


7 Zero, to indicate a format 0. 
8 Object type code of the remote program. 
9-26 Zero (not used). 


Format 1 


The remote program is identified by a descriptor. The subfields are: 
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27-46 


Bytes Content 


7 One, to indicate a format 1. 

8 Normally zero. This byte will usually be zero unless the remote DEC- 
net system identifies the remote program with both name and object 
type code on outgoing connect requests. If nonzero, this byte is inter- 
preted as the object type code of the remote program that sent the 
Connect Initiate Message. 

9 Reserved — must be zero. 

10 Length (in bytes) of descriptor, 0 to 16. Gives the number of charac- 
ters to be interpreted as the program descriptor in the following field 
(bytes 11-26). 

11-26 Remote program descriptor (left-justified). The descriptor used to 
register the remote program for network operations. 


Format 2 


This format identifies the remote program by name or object type code and by 
the group and user codes under which the remote program is running on the 
remote system. (The group and user codes refer to what is called the project- 
programmer number on some DIGITAL systems, including RSTS/E. Other 
DIGITAL systems may refer to these codes as the user identification code, or 
UIC.) DECnet/E systems use this format to identify the sender of a Connect 
Initiate Message. 


The subfields are defined as follows: 


Bytes Content 


7 Two, to indicate a format 2. 

8 Object type code of the remote program, if applicable. If zero, the 
descriptor alone identifies the remote program. 

9 Reserved - must be zero. 

10 Length of descriptor, 0 to 12. Gives the number of characters to be 
interpreted as the program descriptor in the following field (bytes 
11-22). 


11-22 Remote program descriptor, if this is used instead of object type code. 
The descriptor will be left-justified ASCII characters. 

23-24 Remote group code. Binary value giving the group number under 
which the remote program is running. If the remote system is a DEC- 
net/E system, byte 23 is the project number in a RSTS/E project- 
programmer number. 

25-26 Remote user code. Binary value giving the user number under which 
the remote program is running. If the remote system is a DECnet/E 
system, byte 25 is the programmer number in a RSTS/E project- 
programmer number. 


Local Program Name. This field indicates how the remote program addressed 
the local program in the Connect Initiate Message. DECnet/E allows the local 
program to be addressed by object type code or by name, but not both. Again, 
three formats can be used. The subfields are as follows: 


Bytes Content 


27 Format type. Equal to 0, 1, or 2, depending on the format used by the 
remote program to address the local program. 

28 Object type code, if used by the remote program to address the local 
program, (formats 0 or 2). 

29 Always zero. 
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30 


31-36 


37-42 
43-44 


45-46 


Length of name, in bytes. Will be 0 for format 0, 1 to 6 for format 1, 0 
to 6 for format 2. (DECnet/E program names are limited to a maxi- 
mum of 6 characters by the Declare Receiver call.) 

Local program name, if used by the remote program to address the 
local program. (formats 1 or 2). 

Always zero. 

Local group code. Binary value giving the local program’s project 
value, if used by the remote program to address the local program 
(format 2). Zero otherwise (formats 0 or 1). Not used by NSP to 
identify the local program but passed on here. 

Local user code. Binary value giving the local program’s programmer 
value, if used by the remote program to address the local program 
(format 2). Zero otherwise (formats 0 or 1). Not used by NSP to 
identify the local program but passed on here. 


47-92 Access Control Fields. These bytes can be used to define the remote pro- 
gram’s access rights to the local program’s services. The idea is analogous to 
logging into the local system. The local program could use this information to 
log into the RSTS/E system, grant classes of privileges, or whatever. The most 
rigorous checking done in a normal log-in on DIGITAL systems involves user 
identification, password, and account number, so three fields are defined here 
for those items. However, DECnet does not specifically require use of these 
fields at all, nor does it require that the fields be used as described. A DEC- 
net/E system simply passes this information onto the receiving program. 


Bytes 


47 
48 


49-64 


77-92 


Content 


Not meaningful - should be ignored. 

Length of user identification information specified in the next field, 0 
to 16 bytes. 

User Identification. This field identifies the person or program re- 
questing the logical link. In RSTS/E terms, the user ID is analogous 
to the project-programmer number used at log-in. 

Not meaningful - should be ignored. 

Length of password information specified in the next field, 0 to 8 
bytes. 

Password. A password is often used to verify access to a system under 
a particular user identification. In RSTS/E, this password is analo- 
gous to the password used in conjunction with the project-program- 
mer number at log-in. 

Not meaningful - should be ignored. 

Length of the accounting information specified in the following field, 
0 to 16 bytes. 

Accounting Information. Many systems require a billing account 
number in addition to user identification and password. The account- 
ing field is provided for this purpose. 


93-120 Not meaningful - should be ignored. 
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5.7.3 Format of Received Connect Confirm Message 


A received Connect Confirm Message is a remote program’s acceptance of a 
Connect Initiate Message sent by the receiving program. The link is identified 
by the user link address specified by the local program in the Connect Initiate 
Message. The format of the information returned to the target string is de- 
scribed below. Up to 16 bytes of user data can also be returned to the I/O 
buffer specified in the Receive call. 


Bytes 


1-2 


24 
25-26 


27-28 


29-40 


Value 


CHR$(-3%) 
CHR$(ula%) 


remainder% 


length% 


CHR$(rlmod%) 


rmax% 


tmax% 


Description 


Not meaningful - should be ignored. 
Connect Confirm Message subfunction code. 
User link address. 

Not meaningful — should be ignored. 


Number of bytes of data not returned to the I/O buffer. 
This data has been either discarded or saved for a later 
Receive, depending on how the ¢ flag was set in the data 
passed. 


Not meaningful - should be ignored. 


Length (in bytes) of data that was returned to the I/O 
buffer on this Receive. 


Not meaningful - should be ignored. 


Remote link modifier. Indicates the flow control in effect for 
the remote program. The two low-order bits should be 
masked and interpretted as follows: 


flow% = rlmod% AND 3% 


If flow = 0, no flow control 
1, segment flow control 
= 2, message flow control 


Not meaningful - should be ignored. 


Receive maximum, in bytes. The maximum amount of user 
data that will be transmitted to the local program in one 
Network Data Message over this link. This will be (1) equal 
to the rmax value specified in the Connect Initiate Message 
for this link, or (2) a lesser value supplied by the local NSP, 
calculated from the size of the buffers that it allocates for 
receives. 


Transmit maximum, in bytes. The maximum amount of 
user data that can be transmitted by the local program in 
one Network Data Message over this link. This limit has 
been imposed by either the remote program or the remote 
NSP. The local NSP enforces this limit for all Network 
Data Messages sent by the local program on this link. 


Not meaningful - should be ignored. 
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5.7.4 Format of Received Connect Reject Message 


A received Connect Reject Message is a rejection of the receiving program’s 
request for a logical link. It can be from the remote program or from the local 
or remote NSP. The link is identified by the user link address previously 
established in the local program’s Connect Initiate Message. The format of 
the information returned to the target string is described below. Rejections 
from NSP contain a reason code explaining the reason for the rejection and do 
not contain user data. Rejections from the remote program can contain up to 
16 bytes of user data delivered to the I/O buffer. 


Bytes Value Description 
1-2 oa Not meaningful - should be ignored. 
3 CHR$(-4%) Connect Reject Message subfunction code. 
4 CHR$(ula%) User link address, previously defined in the local program’s 
Connect Initiate Message. 
5-8 — Not meaningful - should be ignored. 
9-10 remainder% Number of bytes of data not returned to the I/O buffer. 


This data has been either discarded or saved for a later 
Receive call, depending on how the t flag was set in the 
data passed. 


11-12 == Not meaningful - should be ignored. 

13-14 length% Length (in bytes) of data returned to the I/O buffer on this 
Receive call. 

15-22 — Not meaningful - should be ignored. 

23-24 reason% Identifies the reason for the rejection (see Appendix B). 

25-40 — Not meaningful - should be ignored. 
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5.7.5 Format of Received Network Data Message 


A received Network Data Message contains user data from a remote program. 
The format of the information returned to the target string is described below. 
The user data accompanying the Network Data Message is delivered to the 
I/O buffer specified in the Receive call. 


Bytes 


1-2 


22-40 


Value 


CHR$(-5%) 
CHR$(ula%) 


remainder% 


length% 


CHR$(dmflgs%) 


Description 


Not meaningful - should be ignored. 
Network Data Message subfunction code. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


Number of bytes of data not returned to the I/O buffer. 
This data has been either discarded or saved for a later 
Receive call, depending on how the t flag was set in the 
data passed. 


Not meaningful - should be ignored. 


Length (in bytes) of data that was returned to the I/O 
buffer on this Receive call. 


Not meaningful - should be ignored. 


Data message flags. The two low-order bits indicate 
whether this is the beginning, middle, end, or sole segment 
of a logical message. These bits should be masked. and in- 
terpretted as follows: 


bom% = dmflgs% AND 1% 
eom% = dmflgs% AND 2% 


Then 
eom bom 


0 0 Middle segment of message 
0 1 First segment of message 
2 0 Last segment of message 
2 1 Sole segment of message 


DECnet/E uses the eom bit to determine the end of a logi- 
cal message if the local program requested message flow 
control when the logical link was established. It does not 
use the bom bit but passes it on to the receiving program. 


Not meaningful - should be ignored. 
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5.7.6 Format of Received Interrupt Message 


The local NSP places Interrupt Messages from a remote program at the head 
of the pending message queue, behind the first message and behind any other 
pending Interrupt Messages queued for the program. The format of the data 
returned to the target string is described below. Up to 16 bytes of user data 
can be delivered to the I/O buffer specified in the Receive call. 


Bytes 


1-2 
3 
4 


Value 


CHR$(-6%) 
CHR$(ula%) 


remainder% 


length% 


Description 


Not meaningful - should be ignored. 
Network Interrupt Message subfunction code. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


Number of bytes of data not returned to the I/O buffer. 
This data has been either discarded or saved for later Re- 
ceive calls, depending on how the t flag was set in the data 
passed. 


Not meaningful - should be ignored. 


Length (in bytes) of data returned to the I/O buffer on this 
Receive call. 


Not meaningful - should be ignored. 
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2 


5.7.7 Format of Received Link Service Message 


A Link Service Message provides status information for a particular logical 
link and is only returned on a Receive call when the pending message queue 
has emptied after a condition has cleared that previously inhibited the local 
program from sending (see Section 4.2). Status information with the same 
format as a Link Service Message can also be returned to the target string on 
successful completion of a Send Link Service, Send Network Data, or Send 
Interrupt call. The format of the information returned to the target string is 
described below. No data is delivered to the I/O buffer with a Link Service 
Message. 


Bytes Value Description 

1-2 — Not meaningful - should be ignored. 

3 CHR$(-7%) Link Service Message subfunction code. 

4 CHR$(ula%) User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 

5-8 — Not meaningful - should be ignored. 

9-10 0% Always zero for Link Service. (These bytes are the remain- 
der field in other returned messages.) 

11-12 — Not meaningful - should be ignored. 

13-14 0% Always zero for Link Service. (These bytes are the length 
field in other returned messages.) 

15-20 — Not meaningful - should be ignored. 

21 CHR$(lstat%) Local status flags. These flags should be masked and inter- 


pretted as follows: 


data% = Istat% AND 1% 
intls% = Istat% AND 2% 
Iclbp% = Istat% AND 192% (2-bit field) 


If data = 1, outgoing Network Data Messages are inhibited. 
(A Link Service Message will be delivered when the condi- 
tion clears.) 


If intls = 2, outgoing Interrupt and Link Service Messages 
are inhibited. (A Link Service Message will be delivered 
when the condition clears.) 


The Iclbp value indicates the local NSP’s backpressure 
status: 


0 Incoming Data Message flow is on. 

64 Incoming Data Message flow is on but the local NSP 
will turn this link off if another Data Message is 
received before the local program’s receive queue is 
emptied. 
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Bytes 


22 


23 


24 


25 


26 


27 


28 


29 


30 


Value 


CHR$(rstat%) 


CHR$(ldr%) 


CHR$(lir%) 


CHR$(rdr%) 


CHR$(rir%) 


CHR$(dtm%) 


CHR$(dtc%) 


CHR$(ltm%) 


CHR$(ltc%) 


Description 


128 Incoming Data Message flow has been turned off by 
the local NSP. The local program’s receive queue 
must be emptied before the link will be turned on. 

192 Incoming Data Message flow has been turned off by 
the local NSP but flow is scheduled to turn on as soon 
as system buffers become available. 


Remote status flags. Only one bit is currently defined for 
this field. This bit should be masked and interpretted as 
follows: 


rembp% = rstat% AND 128% 


If rembp = 128, the link has been turned off by the remote 
system due to a backpressure condition. No Data Messages 
can be sent until the remote system turns the link back on. 


Local data request count. The count of segments or logical 
messages currently requested by the local program, reflect- 
ing the actual number of segments or logical messages re- 
quested but not yet received. 


Local interrupt request count. The count of Interrupt Mes- 
sages currently requested by the local program, reflecting 
the actual number of interrupts requested but not yet 
received. This count will never exceed one. 


Remote data request count. The count of segments or logi- 
cal messages currently requested by the remote program, 
reflecting the actual count of segments or messages re- 
quested but not yet sent. 


Remote interrupt request count. The count of Interrupt 
Messages currently requested by the remote program, re- 
flecting the actual count of Interrupt Messages requested 
but not yet sent. 


Data transmit queue maximum. The maximum number of 
data messages that can be queued waiting for acknowledg- 
ment from the remote system. This is a constant set by the 
system manager when NSP is enabled. It applies individu- 
ally to all active logical links. 


Data transmit queue count. The number of data messages 
currently in the data transmit queue for this logical link. It 
is a count of data messages waiting for acknowledgment 
from the remote NSP. 


Interrupt/Link Service transmit queue maximum. The 
maximum number of Interrupt or Link Service Messages 
that can be queued waiting for acknowledgment from the 
remote system. This is a constant set by the system mana- 
ger when NSP is enabled. It applies individually to all ac- 
tive logical links. 


Interrupt/Link Service transmit queue count. The number 
of Interrupt and Link Service Messages currently in the 
Interrupt/Link Service transmit queue for this logical link. 
It is a count of Interrupt and Link Service Messages waiting 
for acknowledgment from the remote NSP. 
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Bytes 


31 


32 


33 


34-40 


Value 


CHR$(mmax%) 


CHR$(ment%) 


CHR$(mula%) 


Description 


Message maximum. The maximum number of incoming 
messages that will be queued for the local program. This 
maximum is set by the program in the Declare Receiver 
call. 


Message count. The total number of messages currently in 
the pending message queue for the local program. 


Message count for this logical link. The number of mes- 
sages currently in the pending message queue for this logi- 
cal link, as identified by the ula (byte 4). 


Not meaningful - should be ignored. 
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5.7.8 Format of Received Disconnect Message 


A received Disconnect Message indicates that an established logical link with 
a remote program has been disconnected by the remote program. All other 
messages sent by the remote program over this logical link have been received 
by the local program. The format of the data returned to the target string is 
described below. Up to 16 bytes of user message data can be returned to the 
I/O buffer specified in the Receive call. 


Bytes 


1-2 


Value 


CHR$(-8%) 
CHR$(ula%) 


remainder% 


length% 


Description 


Not meaningful - should be ignored. 
Disconnect Message subfunction code. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


Number of bytes of user data not returned to I/O buffer. 
This data has been either discarded or saved for a later 
Receive call, depending on how the ¢ flag was set in the 
data passed. 


Not meaningful - should be ignored. 


Length (in bytes) of data delivered to the I/O buffer on this 
Receive call. 


Not meaningful - should be ignored. 
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5.7.9 Format of Received Link Abort Message 


A received Link Abort Message indicates that a logical link has been termi- 
nated by the remote program or by the local or remote NSP. The format of the 
data returned to the target string is described below. Up to 16 bytes of user 
data can be returned to the I/O buffer specified in the Receive call. 


Bytes 


1-2 


5-6 


25-40 


Value 


CHR$(-9%) 
CHR$(ula%) 


lla% 


remainder% 


length% 


reason% 


Description 


Not meaningful - should be ignored. 
Link Abort Message subfunction code. 


User link address (if any), previously defined in the local 
program’s Connect Initiate or Connect Confirm Message. 


Local link address, established by the local NSP for this 
link. It identifies the link if the remote program has sent a 
Connect Initiate Message but the local program has not yet 
responded with a Connect Confirm or Connect Reject Mes- 
sage. No ula exists to identify the link being aborted under 
these conditions. 


Not meaningful - should be ignored. 


Number of bytes of user data not transferred to I/O buffer. 
This data has been either discarded or saved for later Re- 
ceive calls, depending on how the t¢ flag was set in the data 
passed. 


Not meaningful — should be ignored. 


Length (in bytes) of data transferred to the I/O buffer on 
this Receive call. 


Not meaningful - should be ignored. 


Abort Reason (interpreted as a 16-bit integer). If this value 
is nonzero, the link was aborted by either the local or re- 
mote NSP and the reason is specified in these two bytes. 
The reasons that apply for a link abort are listed in Appen- 
dix B. If reason is zero, the link was aborted at the request 
of the remote program. 


Not meaningful - should be ignored. 
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Part IV 


Network Programming 


in 
BASIC-PLUS-2 


Chapter 6 
Network Programming In BASIC-PLUS-2 


This chapter presents the specific calls, with detailed formats, used to access 
the DECnet/E message services in the BASIC-PLUS-2 programming lan- 


{ guage. 


6.1 Programming Background 


To use the RSTS/E message services in BASIC-PLUS-2, you code subroutine 

calls with the CALL BY REF statement. The calls reference external MACRO 

subroutines stored in the system library that must be linked with your pro- 

gram. Thus, the process involves coding, compiling, and linking. These as- 

aN pects of using DECnet/E in BASIC-PLUS-2 are described briefly in the fol- 
© lowing subsections. Specific call formats are given in Sections 6.2 - 6.7. 


6.1.1 Coding 
The general form of the RSTS/E message calls in BASIC-PLUS-2 is: 


CALL name BY REF(arg!, arg2, ...) 
where 


Cc name is the name of one of the 13 subroutines available for mes- 
sage services. Each subroutine processes a call at execu- 
tion time by: 

1. Checking for the proper number of arguments in the 
call. 


2. Translating the call and arguments into the form re- 
cognizable to the RSTS/E monitor. 


3. Passing control to the RSTS/E monitor which in turn 
invokes the NSP software. (In DECnet/E systems, 
NSP is part of the RSTS/E monitor.) 


NSP processes the request and returns control to the user 
program. If an error occurs, NSP returns an error value to 
( an integer variable defined as an argument in each call. 


6-1 


6-2 


arg... is the argument list for the particular call. Values passed 
can be any valid BASIC-PLUS-2 expression of the appro- 
priate type. For example, if the description of an argu- 
ment calls for an integer value, you can supply any valid 
BASIC-PLUS-2 integer constant, variable, or expression. 


NOTE 


CALLs, as opposed to FUNCTIONS, do not 
do implicit type conversions. That is, if an 
integer value is required and you specify a 
floating point value, the floating point 
value will be passed to the message subrou- 
tine. Unexpected fatal errors can result. 


Most calls contain arguments to define buffer areas for sending and receiving 
data. A discussion follows on how buffers can be set up for send and receive 


calls. 


Setting Up Buffers 


You specify either two or three arguments in the DECnet/E message calls to 
define a buffer: a starting address, a length value defining the number of bytes 
in the buffer, and in some cases, an offset in bytes from the beginning of the 
buffer. In all cases, the sends and receives use a contiguous area in computer 
memory to send from or receive to. Thus, for most applications, it is better to 
preallocate space for send and receive buffers rather than to use dynamic 
strings or arrays. The following discussion addresses both methods. 


Preallocating Space 


Use the DIM, COM, or MAP statements to allocate a contiguous block of 
memory at compile time for send and receive buffers. The MAP statement is 
particularly useful. It allocates space and allows the definition of fields within 
the buffer having different data types. You can, for example, define a map 
with a string field, followed by numeric values, followed by another string. 
The same area can also be remapped with different field definitions. For 
example: 


MAP (RETBUF) A$=40% 

MAP (RETBUF) FILL%sCODEULA% +LLA%+FILL%+REMAINDER%»: & 
FILL% +LENGTH% »FILL$=6% sPARAM$=20% 

MAP (RETBUF) FILL% »sCODE$=1% sULA$=1% +LLA% +FILL% +REMAINDER% + & 
FILL%+LENGTH% »sFILL$=6% sPARAM$=20% 


The first MAP statement allocates a 40-byte area. The MAP name is RET- 
BUF and A$ can serve as the starting address argument for a message call. 


The next two MAP statements illustrate two ways of getting at integer byte 
values in BASIC-PLUS-2. The second MAP statement shows an integer field 
CODEULA%, a one-word field that is to be referenced as a one-byte code 
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followed by a one-byte user link address. Once data is in the buffer, you can 
reference the code byte with a statement of the form: 


CODEZ=SWAP(CODEULA%) AND 255% 


And you can reference the ula byte with a statement of the form: 


ULA%=CODEULAZ AND 255% 


The third MAP statement shows the same area in the buffer as two one-byte 
string variables, CODE$ and ULA$. You can then refer to bytes three and 
four as integer values with statements of the form: 


CODE%=ASCII(CODES$) 
ULAZ=ASCIICULAS) 


Using Dynamic Strings and Arrays 


A dynamic string or array is any string or array for which space has not been 
preallocated with a DIM, COM, or MAP statement. BASIC-PLUS-2 allo- 
cates space for dynamic strings and arrays at execution time, not at compile 
time. Except for dynamic string arrays, you can use dynamic values for send 
requests, as shown in the following section, “Buffer Arguments.” The ele- 
ments of dynamic string arrays are not stored contiguously in memory. Hence, 
a send request referring to an entire dynamic string array could include data 
that is not part of the array itself. 


For receive requests, dynamic strings and arrays should not be used at all. 
The amount of data stored in a buffer by a receive request is limited only by 
the length argument in the Receive call. It is not limited by the length of the 
dynamic string or array. Hence, if the data returned by the Receive call is 
longer than the space currently allocated for the dynamic string or array, the 
data stored by the receive will destroy some quantity of data in locations that 
are uncontrolled by the user program. 


Buffer Arguments 


Starting Address: For buffers from which data is to be sent, you can specify 
any valid BASIC-PLUS-2 constant or variable for this argument, except a 
variable naming an entire dynamic string array. 


If you wish to send pure numeric data, for example, you could specify this 
argument as an array name in the form A(), B%(,), and so forth. 


NOTE 


BASIC-PLUS-2 stores two-dimensional array values in contig- 
uous locations by row — (0,0) first, (0,1) second, (0,2) third, 
and so forth. This can be significant if the data is received by a 
remote FORTRAN program that assumes two-dimensional ar- 
rays are stored by column. 
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It can also be practical to specify a string constant as the starting address 
argument for certain types of sends. For example, suppose you wish to notify 
the remote program of a reason for aborting a logical link. You can code the 
call with the string constant ‘““ENDFILE” as the starting address argument. 
You must ensure that the length argument is correct in these cases, however. 


For buffers that are to receive data, the starting address argument should 
name some variable for which space has been preallocated with DIM, COM, 
or MAP, as discussed previously. 


Offset: This argument can be any valid integer value. It defines an offset (in 
bytes) from the starting address where the data to be sent begins. This is 
useful if you are sending segments from a buffer containing an entire logical 
message. 


Length: This argument can be any valid integer value. It defines the total 
number of bytes to be sent or the maximum number of bytes to be received. 
Remember that each character of a string is 1 byte, an integer value is 2 bytes, 
a single-precision floating point value is 4 bytes, and a double-precision float- 
ing point value is 8 bytes. 


6.1.2 Compiling and Linking 


You can compile BASIC-PLUS-2 programs that use the message services to 
run with either the BASIC2 or BP2COM Run-Time System by using the 
COMPILE command. You must use the /OBJECT switch since external 
routines must be linked to the object module produced by compilation to form 
an executable file. You would then use the BUILD command to produce a 
command file and overlay descriptor file for the Task Builder. For example, 
for a source file named NETCOM.B2S stored on the public disk structure, the 
compilation process would be: 


OLD NETCOM (default extension = .B2S) 
COMPILE/OBJECT NETCOM (default extension = .OBJ) 
BUILD NETCOM (default extensions = «CMD and .ODL) 


In the above sequence, the OLD command reads the source file 
NETCOM.B2S from disk into memory where it can be compiled. The COM- 
PILE command with the object switch produces an object module file 
NETCOM.OBJ. (Object module simply means the object code addresses are 
relocatable. Several object modules can then be linked together with the Task 
Builder to produce an executable program.) 


The BUILD command produces two files: a command file (NETCOM.CMD) 
and an overlay descriptor file (NETCOM.ODL). 


You can then link the program with 


TKB @NETCOM 


The Task Builder (TKB) will automatically resolve the references to the 
message subroutines from the system library (LB:SYSLIB.OLB), producing 
the executable file NETCOM.TSK. 
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6.2 Declare Receiver (MDCL) — Privileged (Local and DECnet) 


The MDCL call must be executed before a program can receive any messages 
or send any network messages. (Local messages can be sent without first 
executing this call.) The call defines an identifying object type or name, or 
both, and any restrictions on incoming messages. The monitor associates this 
information with the RSTS/E job number, setting up a Receiver ID Block for 
the job, as described in Section 3.2.3. Only one MDCL call can be in effect at 
a time for a particular job. It remains in effect until a MREM (Remove 
Receiver) call is executed for the job. 


BASIC-PLUS-2 Call Format: 


CALL MDCL BY REF(errval%,name$,objtyp%,access%, 
bmax%o,mmax%,lmax%) 


Argument Descriptions: 
errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MDCL call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘Possible Errors” at the end of this section. 


name 


The logical name is a string consisting of one to six characters. Valid charac- 
ters are uppercase alphanumerics and the special characters “$” (dollar sign), 
“” (period), and “__” (underline). If less than six characters are used, the 
name must be left-justified in the string and the remaining bytes must be 
padded with spaces. (A store into a 6-byte string defined in COMMON or 
MAP will do this automatically.) Leading or embedded spaces are invalid. If 
no name is to be specified (that is, the logical name is null), the string should 
contain 6 spaces. 


Local programs can address the calling program by the logical name. Network 
programs can use either the logical name or the object type code, if one is 
declared. 


For local or network programs to access the calling program by logical name, 
the logical name must be nonnull and unique to the node. That is, only one 
program at the node can declare its identity with that logical name at any 
given time. NSP uses the logical name to identify the calling program for 
queuing messages from local or network programs. If the logical name is null, 
only network access by object type is allowed. (See the following discussion of 
name, objtyp, and access.) 


objtyp 


This integer value specifies the object type code, another form of network 
addressing. As discussed in Section 3.2.1, the object type code defines some 
service the program performs. If the program issuing the MDCL call is ad- 
dressed by object code alone (name is null and access indicates network access 
only), multiple copies can execute at the same time in the RSTS/E environ- 
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ment. Unlike the logical name, the object type code need not be unique within 
the node — multiple copies of a program can declare their identity with the 
same type code at the same time. If name is null, objtyp cannot be zero. 
(Network addressing is discussed in detail in Section 4.1.) 


Acceptable values for the object type code range from 0 through 255. The 
value 0 indicates that other programs in the network will never address the 
calling program by object type code. The range from 1 to 127 is reserved for 
DECnet use (see Appendix A). The range from 128 to 255 is available for 
definition and use by a network installation. 


access 


This integer value consists of the sum of five bit values (/% + p% + n% + 0% + 
s%) that are used to determine access to the declaring program and to modify 
certain aspects of the message operations. 


Three of these bit values (1%, p% and n%) limit the types of senders that can 
queue messages for the calling program. They do not, however, limit the 
messages that the program can send. 


If / = 0, messages from local senders will not be queued for the calling pro- 
gram. (Local senders who use the network functions are considered network 
senders in this context.) If / = 1, messages from local senders will be queued. 


If p = 0, incoming messages from both local privileged and nonprivileged 
senders will be queued for the calling program. If p = 2, incoming messages 
from local senders will be queued only if the sender is privileged. (This bit is 
ignored if / = 0, that is, if no local senders are allowed.) 


If n = 0, incoming requests for logical links are rejected by NSP. If n = 4, 
incoming Connect Initiate Messages are passed on to the receiver, subject to 
the declared message maximum (mmax) and the declared link maximum 
(Imax). In this case, the program must provide its own protection from unau- 
thorized access, if necessary. 


Table 6-1 summarizes access code values and the access permitted for each. 


Table 6-1: Types of Receiver Access 


Access Code Network Local Senders Local Senders 
(n%+p%+I%) Logical Links Privileged Allowed 

0 no no no 

1 no no yes 

2 no no no 

3 no yes yes 

+ yes no no 

5 yes no yes 

6 yes no no 

7 yes yes yes 
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The bit value o is used to regulate single-link programs, modifying the func- 
tion of the program’s declared link maximum (Imax). If o = 0, incoming 
requests for logical links do not affect the program’s link maximum. If 0 = 8, 
however, after queuing an incoming Connect Initiate Message to the receiver, 
NSP sets the program’s link maximum to zero, inhibiting all further incoming 
connect requests. This, in effect, modifies the meaning of the link maximum 
from “one link at a time” to “one link per program execution.” 


By setting this “one-shot” bit value to 8, a program prevents the possibility 
that NSP will queue a Connect Initiate Message for it after its one logical link 
is disconnected and before it issues a Remove Receiver call. 


For example, the DECnet/E FAL utility sets the one-shot bit to 8 and declares 
a link maximum of 1. Once FAL is started as the result of an incoming request 
from a remote NFT utility, NSP queues the Connect Initiate Message and 
zeros the link maximum. Thus, there is no possibility that an incoming con- 
nect request can be queued for that copy between the time that NFT breaks 
the link and the time that FAL issues its Remove Receiver call. This ensures 
that each incoming connect request starts a new copy of FAL. 


Bit value s is used to modify the function of the RSTS/E conditional Sleep 
monitor call. If s = 0, any unreceived message queued for the program will 
block the execution of a conditional Sleep call. This is the normal RSTS/E 
function. If s = 16, however, the RSTS/E monitor will not check the program’s 
message queue when determining whether or not it should in fact suspend 
program execution. Several other conditions (such as a delimiter received on 
an open terminal) can block the Sleep call but a pending message will not. 


logical name, objtyp, and access 


NSP checks the logical name, objtyp, and access arguments to ensure that 
they are consistent. For example, a null logical name and an access allowing 
local senders are inconsistent since local senders can address the program by 
logical name. NSP checks these arguments as shown in Table 6-2. If the 
arguments are invalid, NSP returns an error code of 18 in the errval argument. 
If the arguments are valid, NSP allocates a small buffer to hold the informa- 
tion passed. If no buffers are available, the call fails with errval = 4. A retry 
may succeed. 


bmax 


Until a Receive call (MRCV) is executed, a pending message occupies system 
buffer space. One 16-word buffer from the monitor’s buffer pool is used for 
user- or DECnet-defined parameters and other system-specific information. 
Additional buffer space to hold message data is usually allocated from the 
extended buffer pool. If an extended pool does not exist or no space is avail- 
able there, the monitor’s buffer pool is used. 


Because the monitor pool is a critical system resource, the program must set a 
limit on the amount of space to be used on its behalf. The integer argument 
bmax sets a limit (1 to 32767 bytes) on the total monitor pool space to be used 
for the user data portion of messages. 
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When the number of bytes of monitor pool space used to store message data 
exceeds the calling program’s declared buffer maximum, NSP will no longer 


queue Local Data Messages for the program. An error will be returned to any 


local program that tries to send a Local Data Message to this one. Network 
messages will be queued regardless of the declared buffer maximum but any 
monitor pool space used will be counted against the maximum. 


A zero or negative value indicates that the monitor’s buffer pool is not to be 
used for the user data portion of pending Local Data Messages. 


Table 6-2: System Validation of Name, Object, and Access Parameters 


Access Code Senders Object 
(N%+p%+1I%) Permitted Type Logical Name 


0,2 None Ignored Ignored. 
1,3 Local only Ignored Must be nonnull and unique. 
4,6 Network only Zero Must be nonnull and unique. 


Nonzero If the logical name is null (at least 
one leading binary zero byte), the 
only access permitted is by object 
type code. Multiple copies of the 
program can ccexist. 


If the logical name is nonnull, it 
must be unique at the local node. 
Network senders can refer to the 
calling program by name or by ob- 
ject type code. Only one copy of the 
program using this logical name 
can execute at any given time. 


5,7 Network/Local Any value Must be nonnull and unique so that 
local senders can refer to the calling 
program by logical name. Network 
senders can use the logical name or 
object type code (if objtyp + 0). 
Only one copy of the program using 
this logical name can execute at 
any given time. 


mmax 


The message maximum (mmax), an integer value, limits the number of mes- 
sages that will be queued for the calling program. The value can range from 0 
to 255. 

NSP keeps a count of the total number of messages queued for each declared 
receiver. When one of the these counters equals or exceeds the message maxi- 
mum set by the receiver: 


1. Incoming Local Data Messages are not queued for the receiving program. 
An error is returned to the local sender. 


2. Incoming Connect Initiate Messages cause NSP to determine if another 
copy of the program can be started automatically (see Section 4.1.2). If 
not, NSP rejects the connection and the Connect Initiate Message is not 
queued. A Connect Reject Message is returned to the sender. 
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3. An incoming Network Data Message causes NSP to inhibit incoming data 
messages on that particular logical link and to negatively acknowledge 
(NAK) the message. This forces the remote system to retransmit when 
flow is reenabled. (See Section 4.2.2 for further details on backpressure 
flow control.) 


Imax 

The link maximum (Imax), an integer value, limits the number of incoming 
requests for logical links for the calling program. If the number of links cur- 
rently active is greater than or equal to /max (0 to 63) when a remote Connect 
Initiate Message is received for the program, the local NSP determines if 
another copy of the program can be started automatically (see Section 4.1.2). 
If not, NSP rejects the connection and the Connect Initiate Message is not 
queued. A Connect Reject Message is returned to the sender. 


By declaring a small link maximum, a program can avoid the overhead of 
responding to remote Connect Initiate Messages when it is known beforehand 
that the program can only handle a limited number of logical links. 


A zero value for Imax has the same effect as setting n = 0 in the access 
argument. That is, NSP rejects all incoming requests for logical links to the 
program. The /max argument does not limit the number of logical links initi- 
ated by the program. That is, it does not stop the program from sending 
Connect Initiate Messages. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


3 ACCOUNT OR DEVICE IN USE 


The calling job already exists in the system’s list of declared receivers. This error 
can indicate a logic error in the program or that a previous program running under 
the same job number failed to remove itself from the receiver list before terminat- 
ing. In the latter case, a Remove Receiver call should be issued, followed by 
another Declare Receiver call. (It is common practice to code a Remove Receiver 
call immediately before the Declare Receiver call.) 


4 NO ROOM FOR USER ON DEVICE 


There were no small buffers available to hold the arguments passed with the 
Declare Receiver call. Since the system’s use of small buffers is dynamic, a retry 
may succeed. 


10 PROTECTION VIOLATION 
The calling program must be privileged at the time the Declare Receiver call is 
executed. 

16 NAME OR ACCOUNT NOW EXISTS 


The logical name passed is being used by another job. 
18 ILLEGAL SYS() USAGE 


The parameters passed are inconsistent. See name, object, and access discussion. 
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Example: 


The following example shows a receiver declaration allowing both network 
and local access. Both a logical name (BUS) and an object type code (142) are 
declared. Note that 6 bytes for the logical name were preallocated with COM. 
Thus, when the three characters “BUS” are stored in LNAME$, they are 
stored left-justified with space fill. 


The buffer maximum is set to 512 and the message maximum is set to 5. No 
more than 512 bytes of user message data from incoming Local Data Messages 
will be stored in monitor pool space. And, if more than 5 messages accumulate 
for the program, an incoming request for a connection will cause NSP to check 
to see if another copy of the program can be automatically started. If not, 
NSP will reject the link and any further incoming data messages will cause 
NSP to inhibit incoming message flow on all the program’s logical links be- 
cause of a backpressure condition. The link maximum is set to 2. When the 
program has established two logical links, an incoming Connect Initiate Mes- 
sage will cause NSP to check to see if another copy of the program can be 
started. If not, NSP will reject the link. 


1000 COM LNAME® = 6% & 
NERRVALZ = OZ% & 
\LNAMES = "BUS" & 
NOBUTYP% = 142% & 
NACKSES%Z = 5% & 


\BMAX%Z = 512% & 
\MMAX%Z = SH & 
\LMAX%Z = 2% & 


+ 


* 


2000 CALL MDCL BY REF(ERRVALZ% »sLNAME$ »OBJTYP%+ACKSESZ» & 
BMAK% »MMAXZ +LMAKZ) & 
NIF ERRVALZ< >0% THEN GOTO 12000 


+ 
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6.3 Remove Receiver (MREM) (Local and DECnet) 


The MREM call removes the specified job from the system’s list of declared 
receivers. All pending messages are discarded and any active logical links are 
aborted. This call should be executed at the completion of message process- 
ing. This prevents unwanted messages from accumulating in the queue of 
pending messages. 


Privileged programs can remove other RSTS/E jobs with this call although 
normally, only system utility programs would do this. 


BASIC-PLUS-2 Call Format: 
CALL MREM BY REF(errval‘o,jobx2%c) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MREM call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


jobx2 


A zero value for jobx2 removes the calling job. Privileged programs can re- 
move another local RSTS/E job by specifying job number times two for this 
integer argument. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


10 PROTECTION VIOLATION 


The caller is nonprivileged and has attempted to remove another job. That is, 
jobx2 is nonzero. 


18 ILLEGAL SYS() USAGE 


The jobx2 argument was odd. Jobx2 must be zero to remove the calling job, or job 
number times two to remove another job. 


Example: 


The following example shows a typical Remove Receiver request removing the 
calling job from the system’s list of declared receivers. 


NERRVALZ = O% & 
\CALL MREM BY REF(ERRYVAL% 10%) 
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The NTLN call return information to the calling program concerning the local 
node’s network parameters. Data returned includes the node’s name, address 
and alias (if any), and the default user’s account to be used when an incoming 
Connect Initiate Message does not specify accounting information. (See the 
DECnet/E System Manager’s Guide for a discussion of alias and Section 4.1.4 
of this manual for a discussion of the default user’s account.) 


BASIC-PLUS-2 Call Format: 

CALL NTLN BY REF(errval%, buffer$, buflen%, bufoff%) 
Argument Descriptions: 
errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTLN call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘‘Possible Errors” at the end of this section. 


buffer 


This argument defines the starting address of the buffer to receive the local 
node information. If a nonzero offset is given (see bufoff), the offset is added to 
the starting address specified by buffer. 


When the NTLN call completes successfully, data is returned to the buffer in 
the following format: 


Bytes Contents 


0-5 Local node name, consiting of 1 to 6 uppercase, alphanumeric ASCII characters. 
The name contains at least one alphabetic character. A name shorter than 6 
characters is left-justified and padded to 6 characters with spaces. 


6-7 Local node address, integer value ranging from 1 to 255. 


8-13 Local node alias, consisting of 1 to 6 uppercase, alphanumeric ASCII characters. 
The alias contains at least one alphabetic character. An alias shorter than 6 
characters is left-justified and padded to 6 characters with spaces. If no alias is 
defined, a field of 6 spaces is returned. 


14-15 Local default project-programmer number. Byte 14 = program number; byte 15 = 
project number. If no default account is defined, both bytes are zero. 


buflen 


This integer argument defines the number of bytes to be returned to the buffer 
specified with buffer. If buflen is less than 16 bytes, the call returns only as 
much data as there is room for. For example, if buflen = 8 bytes, the call 
returns only the local node name and address. Sixteen bytes are required to 
receive all the local node parameters. 
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bufoff 

This integer value defines an offset, in bytes, from the address specified by the 
buffer argument. The value of bufoff is added to buffer to define the beginning 
address of the returned data. For example, if offset = 20, the returned data 
begins in byte 21 of the buffer. 


byte 1 20 | 21 (buflen+20) 


whole buffer 


NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 16 and a bufoff 
of 10. If the actual buffer, beginning at buffer was only 16 bytes 
long, the returned data would overwrite 10 bytes beyond the 
end of the buffer. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


Example: 


The following example shows a NTLN call used to obtain all the local node 
parameters. The node name is to be stored in the string variable NAME; the 
address, in the integer variable ADDRSS; the node alias, in the string varia- 
ble ALIAS; and the default project-programmer number, in the integer 
PRJPRG. 


100 MAP (RETBUF) NODDATS = 20% & 
\ MAP (RETBUF) NAME$=6% -ADDRSS% »ALIAS$=6% »+PRIPRG&% 


200 ERRVALZ = O% & 
\ CALL NTLN BY REF(ERRVAL% +NODDAT$ sLEN(NODDAT$) 10%) 
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6.5 Log User Event (NTEV) — Privileged (DECnet) 


The NTEV call permits a user-written program to queue an event to the 
system event processor for logging. Before the event is logged, it is time- 
stamped by the system, in the standard Network Information and Control 
Exchange (NICE) protocol format. The sytem manager can use the normal 
network management SET and CLEAR LOGGING commands to control the 
filtering of these events. Optional data can accompany a user event. 


NOTE 


This system call performs a highly specialized function which 
requires a great deal of special knowledge of DECnet and the 
DIGITAL Network Architecture (DNA). It is provided as a 
convenience for the sophisticated network user and is not in- 
tended for normal network programs. 


BASIC-PLUS-2 Call Format: 


CALL NTEV BY REF(errval%,eumod%,euvcls%,evtyp%,entyp%,enval%, 
buffer$, buflen%, bufoff%) 


Argument Descriptions: 
errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTEV call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


evmod 


This integer argument specifies what the system should do if it is unable to log 
the user event due to lack of resources. If evmod is set to zero, the call 
terminates with a status return of NOROOM (errval = 4); the program can 
retry logging the event after a short delay. If eumod = 1, the system logs a 
“missed event” event message, and the call terminates with a successful 
status (errval = 0). 


Note that in the second case, the user data is not logged. The system merely 
logs the fact that it has lost some unidentified data. This is identical to the 
procedure followed with DECnet internal events when the event queue is full 
or there are no more small buffers. 


evcls 


This integer argument specifies the class of the user event to be logged. Events 
are divided into classes, according to the DNA layer from which they origi- 
nate. Classes 480 to 511 are reserved for customer-specific events. However, 
DECnet/E supports only class 480. Thus, evcls must be 480. 


evtyp 


This integer argument specifies the type of event within the class specified by 
eucls. The event type must be in the range of 0 to 31. 
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entyp 


This integer argument specifies the entity type with which the event is con- 
cerned. There are four entity types supported by DECnet/E, defined as fol- 
lows: 


-1 No specific entity 


0 Node 

1 Line 

3 Circuit 
enval 


This integer argument associates a value to the entity specified by the entyp 
argument. If the entity is a node, enval should be set to the node address. If 
the entity is a line or a circuit, enval should be set to the address of the Device 
Data Block (DDB) maintained for the device. 


buffer 


This argument defines the starting address of the buffer containing the op- 
tional user data to be processed with the event . If a nonzero offset is specified 
(see bufoff), the offset is added to the starting address of the buffer. 

If this data is included, it must be in NICE protocol format. Basically, this 
means that the data should be formatted in a 3-part field: a parameter type, a 
data type, and a parameter value. DECnet parameter types can be used if the 
event concerns a node, a circuit, or a line. In this case, the event logger will 
output standard descriptive text for the specific parameter. If a DECnet pa- 
rameter type is not used, parameter types in the range of 3900 to 4095 can be 
specified. (See the DIGITAL Network Architecture, Network Management 
Functional Specifications, Version 3.0.0, for further information on event defi- 
nitions and parameters.) 


Up to 200 bytes of data can be passed to the event logger for processing. 
buflen 


This integer value defines the number of bytes of data in the buffer specified 
with buffer. Up to 200 bytes of data can be passed. If no data is specified, 
buflen must be 0. 


bufoff 

This integer value defines an offset in bytes, from the address specified in 
buffer. The value of bufoff is added to buffer to define the beginning address 
of the returned data. For example, if bufoff = 20, the data to be processed 
begins in byte 21 of the buffer. 


byte 1 20 | 21 (buflen+20) 


whole buffer 
NOTE 
The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 16 and a bufoff 
of -100. Sixteen bytes of data would be processed, starting with 
the byte at buffer-100. 
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Possible Errors: 


errval Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 
The event queue is full or there are no small buffers available to hold the event. A 
retry may succeed. (This is returned only if eumod = 0.) 

5 CAN’T FIND FILE OR ACCOUNT 
The event logger is not running. Have the system manager start the event logger. 

10 PROTECTION VIOLATION 
The calling program must be privileged at the time the NTEV call is issued. 

18 ILLEGAL SYS() USAGE 
The parameters passed are either inconsistent or invalid. 

66 MISSING SPECIAL FEATURE 
DECnet was not installed at system generation time. The network functions can- 
not be executed. 

Example: 


The following example illustrates the logging of a user event, class 480. and 
type 3. The entity is node number 135. The optional data passed for process- 
ing consists of an /la parameter number (2130) and value. A “missed event” is 
logged if the event itself cannot be. 


100 


200 


300 


400 


MAP (BUFFER) EVTDAT$ = 200% & 
\ MAP (BUFFER) PARMTY% sDATTYP$=1% sDATVAL$=197% 


+ 


EVMOD% = 1% & 


\ EVCLS% = 480% & 
\ EVTYP% = 3% 8 
\ ENTYP%Z = 0% & 
\ ENVALZ = 135% 
PARMTY% = 2130% & 


\ DATTYPS = CHR#(2%) & 
\ PVAL%Z = 40960% & 
\ DATVAL$S = CHRS(PYVAL% AND 255%)+CHRS(SWAPZ(PYAL%) AND 255%) 


+ 


ERRVALZ = O% & 
\ CALL NTEYV BY REF(ERRVAL% sEVMOD% s-EVCLS% +EVTYPZsENTYP%> & 
ENVAL% sEVTDATS sLEN(EVTDATS$) 10%) 
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The NTEV call in the previous example generates the following event mes- 
sage: 


Event type 480.3 


Occurred 14-Dec-81 15:31:39.7 on node 135 (GROK) 
Node address 135 (GROK) 
Parameter #2130 = 40960 
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There are nine separate send calls — one local and eight network. Each of 
these calls causes NSP to format a message that is then either queued to a 
local program or transmitted across the network to a remote program. 


6.6.1 Send Local Data Message (MSLD) (Local) 


The MSLD call sends up to 532 bytes of user data to another program on the 
local RSTS system. The other program must be a declared receiver of local 
messages. If the other program has declared that only privileged local senders 
are allowed, the calling program must be privileged or the MSLD will fail with 
an error. The receiving program is identified in the MSLD call either by its 
job number or by the logical name with which it declared itself a receiver. 


BASIC-PLUS-2 Call Format: 


CALL MSLD BY REF(errval%,jobx2%,name$, buffer?, buflen%, 
bufoff%,parptr? ,parlen%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MSLD call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘Possible Errors” at the end of this section. 


jobx2 


If jobx2 is zero, the message data is sent to the local program identified by the 
name argument. Otherwise, the message data is sent to the program whose job 
number (times two) is equal to the value of jobx2. For Example, if jobx2 = 8, 
the message is sent to job 4. 


name 


The logical name identifies the intended local receiver when the Jobx2 argu- 
ment = 0. The receiver must have declared its identity with this name in its 
Declare Receiver call. It is a string consisting of one to six characters. Valid 
characters are uppercase alphanumerics and the special characters “$” (dollar 
sign), “*.” (period), and “‘__”’ (underline). If less than six characters are used, 
the name must be left-justified in the string and the remaining bytes must be 
padded with spaces. (A store into a 6-byte string defined in COMMON or 
MAP will do this automatically.) Leading or embedded spaces are invalid. 
This field is ignored when jobx2 + 0. 


buffer 


This argument defines the starting address of a buffer from which message 
data is to be sent. The data is assumed to be in contiguous bytes in the buffer. 
(See Section 6.1.1 for a discussion of different ways to set up buffers for 
message services in BASIC-PLUS-2.) If a nonzero offset is given (see bufoff) 
the offset is added to the starting address specified by buffer. 
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buflen 


This integer argument defines the number of bytes to be sent from the buffer. 
Possible values for buflen range from 0 through 512. 


bufoff 


This integer value defines an offset, in bytes, from the address specified by the 
buffer argument. The value of bufoff is added to the starting address of the 
buffer to define the beginning address of the message data to be sent. For 
example, if offset = 20, the user data begins in byte 21 of the buffer. 


byte 1 20| 21 (buflen+20) 


whole buffer 


NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 512 and a bufoff 
of 1000. The MSLD call would send 512 bytes beginning at 
buffer+1000. 


parptr 


This argument defines an area containing up to 20 bytes of parameter mes- 
sage data to be sent to the local program. This data will be delivered separate 
from the message data in the buffer area. For example, a RSTS BA- 
SIC-PLUS-2 program issuing a Receive call that returns a Local Data Mes- 
sage will get the parameter data and the message data in two separate buffers 
defined in the Receive call. 


parlen 


This integer value defines the number of bytes to be sent from the parameter 
area defined by parptr. The parlen value can range from 0 through 20. 


Possible Errors: 


errval Error Text and Meaning 


4 NO ROOM FOR USER ON DEVICE 


The number of pending messages for the intended local receiver is at its declared 
maximum. The program should try again later. If this error occurs repeatedly, the 
receiver is not processing messages often enough. 


5 CAN’T FIND FILE OR ACCOUNT 


The intended local receiver could not be located in the system’s list of declared 
receivers. The receiver must be declared (with a Declare Receiver call) before any 
data can be transmitted to it. 


10 PROTECTION VIOLATION 


Some access violation has occurred. Either the receiver does not allow any local 
senders or the sender is nonprivileged and the receiver allows only privileged 
senders. 


(continued on next page) 
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errval Error Text and Meaning 


18 ILLEGAL SYS() USAGE 


The value of jobx2 is odd. It must be 0 or the receiver’s job number times two, 
31 ILLEGAL BYTE COUNT FOR I/O 


Either the buflen value or the parlen value is invalid. The buflen argument can 
range from 0 through 512. The parlen argument can range from 0 through 20. 


32 NO BUFFER SPACE AVAILABLE 


System buffers are currently not available to store this message for the intended 
local receiver. A later retry may proceed without error. 


Example: 


The following example shows a local send to a program that has issued a 
Declare Receiver call with the logical name LOCAL. A buffer length (buflen 
argument) of 8 and offset of 18 indicate that the characters ‘OFFSET’ are 
sent. No parameter message data is sent. 


1000 COM A#® = 512% & 
\COM LNAME# =G6% & 
NERRYVALZ = O% & 
\AS = "TO ILLUSTRATE THE "OFFSET" & 
\LNAME$S = "LOCAL" & 
\BUFLEN% = 8% & 
\BUFOFF% = 18% & 
\CALL MSLD BY REFC(CERRVAL% 10% +LNAMES +A$ »sBUFLEN%Z>+ & 
BUFOFF% 10% 10%) 
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6.6.2 Send Connect Initiate Message (NTCI) (DECnet) 


The NTCI call is used to request a logical link to another program. The other 
program is identified with a Connect Data Block and the user link address by 
which the calling program will refer to this link is established. Other argu- 
ments specify the flow control option and maximum amount of user data for 
received Network Data Messages. Up to 16 bytes of user data can be sent with 
the NTCI call. 


BASIC-PLUS-2 Call Format: 


CALL NTCI BY REF(errval%,ula%,llmod%,rmax%, buffer?, 
buflen%, bufoff%) 


Argument Descriptions: 
errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTCI call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


ula 


The user link address (ula) is an integer value within the range 1 to 255. Later 
calls to send and receive messages use this value to refer to the logical link 
(assuming that the link being requested by the NTCI is accepted by the 
remote NSP and the remote program). 


The ula must be unique within the program at any given time. That is, one 
program cannot have two different logical links with the same ula at the same 
time. 


Ilmod 


The integer value llmod indicates the type of flow control requested by the 
calling program to control incoming data from the remote program. Accept- 
able values and meanings are: 


0 No flow control 
1 Segment flow control 
2 Message flow control 


Flow control is described in detail in Chapter 4. Remember that each program 
in a logical link selects its own flow control. The //mod value is the selection 
made by the local program. If l/mod is nonzero, the program must issue Link 
Service (NTLS) calls to request Network Data Messages from the other pro- 
gram. 


rmax 


A program that has limited buffer space and is not designed to process large 
messages in small pieces, can impose a limit on the amount of user message 
data it is willing to receive on a logical link. The integer value rmax specifies 
this limit in bytes. 
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The size of the receive buffers allocated by NSP will itself limit the amount of 
data that can be passed in a single Network Data Message. If the maximum 
size set for NSP by Network Management is not large enough to handle the 
receive maximum as specified in rmax, the local NSP will alter the maximum 
to the smaller limit before forwarding the Connect Initiate Message to the 
remote node. If rmax = 0, NSP will supply the size of its receive buffers as a 
default value. (The calling program will be informed of any such change by a 
field in the Connect Confirm Message from the target program when the link 
is accepted.) 

The remote NSP uses this value to establish a transmit maximum for its end 
of the logical link. If the remote system is also a RSTS system, this transmit 
maximum is passed on to the remote program. The remote program must 
limit the amount of user message data it sends over the logical link according 
to this value. 

See the discussion of the buflen argument with the Receive call (MRCV) in 
Section 6.7 for a description of how to process large messages in small pieces. 


buffer 


This argument defines the starting address of a buffer for the Connect Data 
Block and optional user message data. The 120-byte Connect Data Block and 
up to 16 bytes of message data are assumed to be in the buffer in contiguous 
bytes. (See Section 6.1.1 for information on how to set up a buffer in BA- 
SIC-PLUS-2.) If a nonzero offset is given (see bufoff), the offset is added to 
the starting address of the buffer. 

The Connect Data Block identifies the target program for the requested logi- 
cal link. Figure 6-1 shows the format of the Connect Data Block. The fields 
within the block are described in Table 6-3. 


Up to 16 bytes of user data can follow the Connect Data Block. 
buflen 


This integer value defines the number of bytes to be sent. Since the Connect 
Data Block is 120 bytes long and the optional user data can be from 0 to 16 
bytes long, acceptable values for buflen range from 120 through 136. 


bufoff 


This integer value defines an offset, in bytes, from the start of the buffer from 
which the data is to be sent. The offset value is added to the starting address 
of the buffer to define where the Connect Data Block begins. For example, if 
bufoff = 20, the Connect Data Block begins in byte 21 of the buffer. 


byte 1 20 | 21 140 | 141 


whole buffer 
NOTE 
The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. If a 
program’s buffer is 100 bytes long, for example, with a specified 
offset of 20 and a length of 136, 136 bytes will be sent: the last 
80 bytes of the buffer and 56 bytes of whatever is beyond the 
buffer in memory. 
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Figure 6-1: Format of Connect Data Block on Send Connect Initiate 


Table 


Bytes 


1-6 


7-26 


6-3: Format of Connect Data Block on Send Connect Initiate 
Message 


Content 


Remote Node. 1 to 6 uppercase, alphanumeric ASCII characters naming the 
remote node to which the Connect Initiate Message is to be sent. The name must 
contain at least one alphabetic character, and names shorter than six characters 
must be left-justified and padded to six characters with spaces. If no node name 
is to be specified (that is, the request is directed to a program at the local node), 
this field should contain 6 spaces. 


Remote Program. Identifies the remote program to which the Connect Initiate 
Message is directed as either an object type (general function) or a specific 
entity (program, task, or process) This identification is given in one of three 
formats: 


Format 0 
The remote program is identified by object type code alone. The fields are: 
Bytes Content 


7 Zero, to indicate a format 0 name. 
8 Object type code of the remote program. 
9-26 Zero (Not used). 


(continued on next page) 
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Table 6-3 (Cont.): Format of Connect Data Block on Send Connect 


27-46 


Initiate Message 


Format 1 


The remote program is identified by a descriptor. The fields are: 


Bytes Content 


7 One, to indicate a format 1 name. 

8 Normally zero. This byte should be zero unless the target DECnet 
system allows identification by both name and object type code on 
incoming connect requests (DECnet does not). If nonzero, this byte is 
interpreted as the object type code of the remote program for which the 
Connect Initiate Message is intended. 

9 Reserved - must be zero. 

10 Length of descriptor, 0 to 16 bytes. Gives the number of characters to 
be intgrpreted as the program descriptor in the following field. 

11-26 Remote program descriptor (left-justified). For a DECnet program, this 
is the logical name that the remote program defined in its Declare 
Receiver call. For other systems, it is the descriptor used to register the 
program for network operations. 


Format 2 

This format allows identification of the remote program by name or object type 
code and by the group and user codes under which the remote program is 
accessible on the remote system. (The group and user codes refer to what is 
called the project-programmer number on some DIGITAL systems, including 
RSTS. Other systems refer to these codes as the user identification code, or 
UIC.) DECnet systems use only the object type code or descriptor to find or start 
the target program for which a Connect Initiate Message is intended. The group 
and user codes are simply passed on to the target program for its own checking. 
Other DECnet systems can handle an incoming connect request in format 2 
differently. 

The subfields are defined as follows: 

Bytes Content 


7 Two, to indicate a format 2 name. 

8 Object type code of the remote program, if applicable. If zero, the 
descriptor must be used. 

9 Reserved - must be zero. 

10 Length of descriptor, 0 to 12 bytes. Gives the number of characters to 
be interpreted as the program descriptor in the following field (bytes 
11-22). 


11-22 Remote program descriptor, if this is used instead of object type code. 
The descriptor should be left-justified in the field. 

23-24 Remote group code. Binary value giving the group number under which 
the remote program is running or is to be started. Corresponds to the 
project number in a RSTS project-programmer number. This value is 
not used by DECnet systems but is simply passed on to the receiving 
program. 

25-26 Remote user code. Binary value giving the user number under which 
the remote program is running or is to be started. Corresponds to the 
programmer number in a RSTS project-programmer number. This 
value is not used by DECnet systems but is simply passed on to the 
receiving program. 


Local Program. This field is filled in by the local NSP using information that 
the local program specified in its Declare Receiver call. Any values passed by the 
user program in this area are ignored. 


(continued on next page) 
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Table 6-3 (Cont.): Format of Connect Data Block on Send Connect 
Initiate Message 


The information is passed to the remote system in format 2, as described previ- 
ously. Byte 27 is filled in with a value of 2. Byte 29 is always zero. If the program 
declared its identity with object type alone, the object type code is passed in 
byte 28 and bytes 30-42 are zero. If the program declared its identity with a 
logical name, or with a logical name and object type code, the local name is 
supplied in bytes 31-42 and byte 28 is zero. The length of the logical name is 
given in byte 30. The project-programmer number under which the program is 
running is passed in bytes 43-46 as the group and user codes. The project 
number is in byte 43. The programmer number is in byte 45. Both are in binary 
format. 

47-92 Access Control Fields. These bytes can be used to define the calling program’s 
access rights to the remote system or to the remote system’s services. The idea is 
analogous to logging in on the remote system. The most rigorous checking done 
in a normal log-in on DIGITAL systems involve user identification, password, 
and account number, so three fields are defined here for those items. However, 
overall DECnet design does not specifically require use of these fields at all nor 
does it require that the fields be used as described. A DECnet system simply 
passes this information on to the receiving program. To determine what, if 
anything, a non-RSTS DECnet system requires in these fields, see the DECnet 
manual for that system. 

NOTE 


The DECnet utilities NFT and NETCPY, that use logical links to 
access remote files and devices, use these fields to establish the 
local terminal user’s right to access remote files and devices. Both 
utilities prompt the local user for log-in information to be used at 
the remote system and pass that information along in the Con- 
nect Data Block of the Connect Initiate Message. The remote 
FAL or receiving NETCPY checks this information before allow- 
ing the operation requested. 
Bytes Content 


47 Reserved — must be zero. 
48 Length of user identification information specified in the next field, 0 
to 16 bytes. 


49-64 User Identification. This field identifies the person or program request- 
ing the logical link. In RSTS terms, the user ID is analogous to the 
project-programmer number used at log-in. This information need only 
be specified here if it is required by the remote system or program. If it 
is not required, the length (byte 48) should be set to zero. 

65 Reserved - must be zero. 

66 Length of password information specified in the next field, 0 to 8 bytes. 

67-74 Password. A password is often used to verify access to a system under a 
particular user identification. In RSTS, this password is analogous to 
the password used in conjunction with the project-programmer number 
at log-in. A password supplied here must be acceptable to the remote 
system or program, if one is required. If not required, the length (byte 
66) should be set to zero. 


75 Reserved -— must be zero. 
76 Length of the accounting information specified in the following field, 0 
to 16 bytes. 


77-92 Accounting information. Many systems require a billing account num- 
ber in addition to user identification and password. The accounting 
field is provided for this purpose. Once again, such information need 
only be specified here if it is required by the remote system or program. 
If it is not required, the length (byte 76) should be set to zero. 


(continued on next page) 
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Table 6-3 (Cont.): Format of Connect Data Block on Send Connect 


93-120 


Initiate Message 


Reserved for future use. Currently ignored by DECnet but should be passed as 
zeros. 


Possible Errors: 


errval 


1 


14 


17 


18 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 


system manager. 


ACCOUNT OR DEVICE IN USE 


The calling program already has a logical link with the same user link address 
(ula) as specified in this Connect Initiate Message. A different ula must be used or 


the existing link must be disconnected. 


NOT A VALID DEVICE 


The node named in the Connect Data Block is not known to the system. 


DEVICE HUNG OR WRITE LOCKED 


The node named in the Connect Data Block is known to the system but is cur- 


rently inactive. There is no physical communication path to the node. 


TOO MANY OPEN FILES ON UNIT 


The total number of logical links allowed for the local node has been reached. A 
later try may succeed. (The system manager can set a limit on the total number of 


links. If this limit is inadequate, see the system manager.) 


ILLEGAL SYS() USAGE 


One of several possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The Declare Receiver call for the calling program had a null logical name 
and a zero object type code. There is no way to identify the program to the 
remote system. Issue a Remove Receiver call and reissue the Declare Re- 
ceiver call. 


3. An invalid value was detected in one of the following fields. 


Remote program field in the Connect Data Block. 
One of the three access control fields in the Connect Data Block. 


The user link address (ula) given was zero. Valid values range from 1 to 
255. 


The local link modifier (/imod) value must be 0, 1, or 2. 


The remote descriptor length (byte 10 in the Connect Data Block) was 
nonzero but the descriptor field was null (all zeros). 


(continued on next page) 


Network Programming in BASIC-PLUS and BASIC-PLUS-2 


errval Error Text and Meaning 
22 DISK PACK IS LOCKED OUT 


NSP cannot create a new logical link because the physical line to the remote node 
or the local node itself has been scheduled for shutdown by the system manager. 


31 ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 120 bytes and 136 bytes for a Connect Initiate Message. 


32 NO BUFFER SPACE AVAILABLE 
System buffers are not currently available to store this message. A later try may 
succeed. 

62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


Example: 


The following example shows a Connect Initiate Message directed to a pro- 
gram named NETRCV at node MIAMI. The Connect Data Block uses a 
format 1 name to address the remote program. (Note the use of the SWAP% 
function to place a value of 6 in byte 10 of the Connect Data Block.) NSP 
supplies the local program identification and no access control fields are used. 
Thus, the rest of the Connect Data Block is filled with zeros. Message data is 
sent following the Connect Data Block. Note that 16 bytes of user message 
data are actually sent. Storing into a string field defined by MAP causes space 
fill in the field. Thus, the LEN function will return a value of 136. 


1000 MAP (SNDCI) CONDATS = 136% & 
\MAP (SNDCI) NODES = G%r+FMT%+LGT% »NAMES=16%>% & 
FILL#(94%)=CHR#(0%) »MSG$=16% & 


* 


\NULAZ = 27% & 
\LLMOD% = 2% & 


\RMAK%Z = 312% & 
\NODES = "MIAMI" & 
\FMT% = 1% & 

\LGT% = SWAPZ(6%) & 
\NAMES = "NETRCY" & 
\MSG$ = "OPTION2" & 


+ 


+ 


\CALL NTCI BY REFC(CERRVAL% »ULAZ»+LLMOD% »RMAXZs & 
CONDAT# +LEN(CONDATS) 10%) 
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6.6.3 Send Connect Confirm Message (NTCC) (DECnet) 


The NTCC call is used to accept a remote program’s request for a logical link. 
The call establishes the user link address that the calling program will use to 
refer to the link. The local link address assigned by the local NSP identifies 
the particular link being accepted. The flow control option and the receive 
maximum for the link are specified and up to 16 bytes of message data can be 
passed to the remote program. 


BASIC-PLUS-2 Call Format: 


CALL NTCC BY REF(errval%o,ula%,lla%,llmod%,rmax%, 
buffer? ,buflen%, bufoff%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTCC call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘“‘Possible Errors” at the end of this section. 


ula 


The user link address (ula) is an integer value within the range 1 to 255. Later 
calls to send and receive messages use this value to refer to the logical link. 


The ula must be unique within the program at any given time. That is, one 
program cannot have two different logical links with the same ula at the same 
time. 


lla 


The local link address (lla) is an integer value that identifies the link being 
accepted. It is a number assigned by the local NSP when it received the 
Connect Initiate Message requesting the link. The local link address is passed 
to the local program in bytes 5-6 of the received Connect Initiate Message. 
(Section 6.7.2 describes the information returned for a received Connect Initi- 
ate Message.) 


limod 


The integer value //mod indicates the type of flow control requested for this 
end of the logical link. Acceptable values and meanings are: 


0 No flow control 
1 Segment flow control 
2 Message flow control 


Flow control is described in detail in Chapter 4. Remember that both pro- 
grams in a logical link select their own flow control, independent of each 
other. The ll/mod value is the selection made by the local program. If llmod is 
nonzero, the program must issue Link Service (NTLS) calls to request Net- 
work Data Messages from the other program. 
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rmax 


A program could have limited buffer space and not be coded to process large 
messages in small pieces. Such a program can impose a limit on the amount of 
user message data it is willing to receive on a logical link. The integer value 
rmax specifies this limit in bytes. 


The size of the receive buffers allocated by NSP will itself limit the amount of 
data that can be passed in a single Network Data Message. If the maximum 
size set for NSP by Network Management is not large enough to handle the 
receive maximum as specified in rmax, the local NSP will alter the maximum 
to the smaller limit before forwarding the Connect Confirm Message to the 
remote node. If rmax = 0, the local NSP will supply the size of its receive 
buffers as a default value. 


The remote NSP uses this value to establish a transmit maximum for its end 
of the logical link. If the remote system is also a RSTS system, this transmit 
maximum is passed on to the remote program. The remote program must 
limit the amount of user message data it sends over the logical link according 
to this value. 


See the discussion of the buflen argument for the Receive call (MRCV) in 
Section 6.7 for a description of how to process large messages in small pieces. 


buffer 


This argument defines the starting address of a buffer for the optional user 
message data. The data is assumed to be in the buffer in contiguous bytes. 
(See Section 6.1.1 for a discussion of how to set up buffers for message opera- 
tions in BASIC-PLUS-2.) If a nonzero offset is given (see bufoff), the offset is 
added to the starting address of the buffer. 


buflen 
This integer value defines the number of bytes of user data to be sent: 0 to 16. 
bufoff 


This integer value defines an offset, in bytes, from the address specified by the 
buffer argument. The offset value is added to the starting address of the buffer 
to define where the user data begins. For example, if bufoff = 20, the user data 
begins in byte 21 of the buffer. 


byte 1 20 | 21 (buflen+20) 


whole buffer 


NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 16 and a bufoff 
of -100. Sixteen bytes beginning at buffer-100 would be sent. 
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Possible Errors: 


errval 


10 


18 


31 


32 


62 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


ACCOUNT OR DEVICE IN USE 


A logical link is currently active for the calling program with the same user link 
address (ula) as specified in this Connect Confirm Message. A different ula must 
be used or the existing link must be disconnected. 


CAN’T FIND FILE OR ACCOUNT 


The local link address (l/a) does not correspond to any known logical link for the 
calling program. Either the /la is incorrect or the originating connect request has 
been cancelled. In the latter case, a Link Abort Message has already been queued 
for this link. The /la field in the received Link Abort Message identifies the link, 
since no ula was ever established. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Connect Confirm Message for a 
link that is not waiting for confirmation will cause this error. For example, a 
second Connect Confirm Message for the same logical link will cause this error 
because the link is already established. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. An invalid value was detected in one of the following fields. 


e The user link address (ula) given was zero. Valid values range from 1 to 
255. 


¢ The local link modifier (/imod) value must be 0, 1, or 2. 
ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. It must be between 0 and 16 (bytes) 
for a Connect Confirm Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 
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Example: 


In this example, an NTCC call responds to a received Connect Initiate Mes- 
sage that was stored in the receiving string REC$. The local link address is 
stored in bytes 5 and 6 of such a string and the second MAP statement has 
been used so that LLA% obtains this integer value. The call also establishes a 
user link address of 15, a receive maximum of 256 bytes, and indicates that 
the program requests message flow control. No user message data is sent, so a 
null dynamic string and zero values are used for the buffer arguments. 


1000 MAP (RETBUF) RECS = 40% & 

\MAP (RETBUF) FILLS = 4%+LLAZ+FILL%»REMAINDERZ» & 
FILL%+LGT% +FILL$=8% sRLMOD$=1% sFILLS=1%% & 
RMAX%Z +TMAKZ & 

\ERRVAL%Z = O% & 

\ULAZ = 15% & 

\LLMOD% = 2% & 

\RMAX% = 256% & 

\CALL NTCC BY REF(ERRVAL%+ULAZ+LLAZ »LLMODZ» & 
RMAX% sNOBUFS 10% 10%) 
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6.6.4 Send Connect Reject Message (NTCR) (DECnet) 


The NTCR call is used to reject a remote program’s request for a logical link. 
The link is identified by the local link address established by the local NSP. 
Up to 16 bytes of user message data can be sent to the remote program as part 
of the Connect Reject Message. 


BASIC-PLUS-2 Call Format: 
CALL NTCR BY REF(errval%,lla%,reason%, buffer? , buflen%, bufoff%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. If the NTCR call 
succeeds, this variable is set to zero. If an error occurs, errval is set to one of 
the error codes listed under “Possible Errors” at the end of this section. 


Hla 


The local link address (lla) is an integer value that identifies the link being 
rejected. It is a number assigned by the local NSP when it received the 
Connect Initiate Message requesting the link. The local link address is passed 
to the local program in bytes 5-6 of a received Connect Initiate Message. 
(Section 6.7.2 describes the information returned for a received Connect Initi- 
ate Message.) 


reason 


DECnet/E NSP allows one of the following three reason code values for this 
word: 0, 34, or 36. 


Most user programs will simply use 0. If any reason is supplied for rejecting 
the connection, it is passed in the 16-byte user data area. 


The values 34 and 36 are provided so that DECnet/E support programs (such 
as FAL and NFT) can reject unauthorized or improper requests for access to 
local RSTS/E files in a manner agreed upon as part of the overall DECnet 
design. There is no reason for a user program to use these codes unless it talks 
to programs that interpret them. All DECnet programs that are concerned 
with protection against unauthorized access are designed to recognize these 
codes. These programs take appropriate action, such as displaying an error 
message to a user, when they receive such a connect rejection. 


The value 34 indicates that the user ID and password subfields in the Connect 
Data Block of the remote program’s Connect Initiate Message do not corre- 
spond to any valid user known to the local system. 


The value 36 indicates that, while the user ID and password subfields are 
acceptable, the account subfield is not. For example, the specified user may 
not be authorized to use that billing account or the account may be ex- 
hausted. 
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buffer 


This argument defines the starting address of the buffer containing the op- 
tional user message data. The data is assumed to be in the buffer in contigu- 
ous bytes. (See Section 6.1.1 for a discussion of how to set up buffers for 
message operations.) If a nonzero offset is given (see bufoff), the offset is 
added to the starting address of the buffer. 


buflen 
This integer value defines the number of bytes of user data to be sent: 0 to 16. 
bufoff 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufoff is added to the buffer 
address to define the beginning address of the user message data. For exam- 
ple, if bufoff = 20, the user data begins in byte 21 of the buffer. 


byte 1 20 | 21 (buflen+20) 


whole buffer 





NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 16 and a bufoff 
of -100. Sixteen bytes beginning at buffer-100 would be sent. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


5 CAN’T FIND FILE OR ACCOUNT 


The local link address (Ila) does not correspond to any known logical link for the 
calling program. Either the lla is incorrect or the originating connect request has 
been cancelled. In the latter case, a Link Abort Message has already been queued 
for this link. The Ila field in the received Link Abort Message identifies the link, 
since no ula was ever established. 


10 PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Connect Reject Message for a link 
that is not waiting for confirmation will cause this error. For example, sending a 
Connect Reject Message for a link that is already established will return this 
error. 


(continued on next page) 
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errval 


18 


31 


32 


62 


Error Text and Meaning 


ILLEGAL SYS() USAGE 


One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 
2. The reason code supplied in the Connect Reject Message call was not 0, 34, or 


36. 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 bytes for a Connect Reject Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 


succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 


not be executed. 


Example: 


In this example, a NTCR call responds to a received Connect Initiate Message 
stored in the receiving buffer R$. A reason code of 0 is supplied. The local 
program notifies the remote program of the reason for rejection with user data. 


1000 MAP 


(RETBUF) R& 


= 40% & 


\MAP (RETBUF) FILLS = 4%sLLAZ+FILLZ+REMAINDERZ sFILL% > & 
LGT% »FILL$=8% sRLMODS$=1% sFILLS=1% sRMAXZ + TMAXZ & 


VERRVALZ 
\BUFFERS 
\BUFLEN% 
\BUFOFF% 
\REASON% 


O% & 
"TOO 
Bz & 
O% & 
O% & 


LATE" & 


\CALL NTCR BY REFCERRVAL%»LLAZ »REASONZ sBUFFERS:s & 
BUFLEN% »BUFOFF%) 
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6.6.5 Send Network Data Message (NTDM) (DECnet) 


The NTDM call transmits user data — a segment, as defined in Chapter 4 — 
over an established logical link. A flag byte indicates whether or not the 
segment is the end of a logical message. If the remote program requested 
segment or message flow control when the link was established, requests for 
data must be outstanding or this call will result in an error. 


BASIC-PLUS-2 Call Format: 


CALL NTDM BY REF(errval%,retbuf? ula%,dmflgs%, buffer? , 
buflen%, bufoff%) 


Argument Descriptions: 


errval 

The errval argument must be an integer variable name. This variable is set to 
zero if the NTDM call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘“‘Possible Errors” at the end of this section. 


retbuf 

This argument names the buffer to receive link status information returned by 
the call. This argument must be specified regardless of whether or not link 
status information is requested and should refer to a preallocated buffer at 
least 40 bytes long. 


ula 

The ula is an integer value giving the user link address (1 to 255) chosen by 
the calling program in the Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


dmfigs 
The dmflgs argument can be coded as the sum of three bit values: 


dmflgs% = rls% + eom% + bom% 


The low-order two bits of the dmflgs argument (eom% + bom%) indicate 
whether the segment being sent in this Network Data Message is the first, 
last, middle, or sole segment of a logical message. If message flow control was 
requested by the remote program when the link was established, NSP uses 
these two bits to regulate the transmission of logical messages as the remote 
program requests them. (See Chapter 4 for a full discussion of flow control.) 
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0 0 Middle segment of a logical message 


0 1 First segment of a logical message 
2 0 Last segment of a logical message 
2 i Sole segment of a logical message 


DECnet/E NSP uses the eom bit to count logical messages transmitted to the 
remote program. The bom bit is not used in maintaining the logical message 
request count but is simply passed to the remote system and program. 


NSP also uses the eom bit to determine whether it will permit a disconnect of 
the logical link. If a disconnect is requested but the last Network Data Mes- 
sage sent did not have the eom bit set, NSP assumes that the last message has 
not been completely sent and will reject a Disconnect Message. This is always 
done, irrespective of the flow control option selected by the remote program. 


Some DECnet implementations require that the eom flag be set to terminate 
an asynchronous I/O operation. Thus, when the remote program requests 
segment flow control or no flow control, the eom flag should always be set. 
Setting the bit in this case will not affect a remote DECnet/E node but is 
essential if the remote node is a DECnet node waiting to terminate asynchro- 
nous I/O. 


The rls bit is used to request that link status information be returned to the 
retbuf argument when this call is successfully completed. 


rls = 128 Link status information is returned. 
rls = 0 No link status information is returned. 


If link status information is requested, it is returned in the same format as a 
received Link Service Message (Section 6.7.7). The MAP statement is partic- 
ularly useful to allocate the buffer, as it both allocates the space for the 
information and allows the definition of named fields with different data 
types within the buffer (see Section 6.1.1). 


If no link status information is requested, random data is returned. 


buffer 


This argument defines the starting address of a buffer containing the user 
message data. The data is assumed to be in contiguous bytes. (See Section 
6.1.1 for a discussion of how to set up buffers in BASIC-PLUS-2.) If a nonzero 
offset is given (see bufoff), the offset is added to the starting address of the 
buffer. 


buflen 


This integer value defines the number of bytes to be sent. The maximum 
amount of data that can be transferred over the logical link is established by 
the remote program or remote NSP. It is passed on to the local program as the 
transmit maximum — the tmax value in a received Connect Initiate or Con- 
nect Confirm Message (Sections 6.7.2 and 6.7.3). Thus, the value of buflen 
can range from 1 through tmax. 
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bufoff 


This integer value defines an offset, in bytes, from the starting address of the 
buffer defined by the buffer argument. The value of bufoff is added to the 
buffer address to define the beginning address of the user message data. For 
example, if bufoff = 20, the user data begins in byte 21 of the buffer. 


byte 1 20 | 21 (buflen+20) 


user data 





whole buffer 


NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 100 and a bufoff 
of 20. One hundred bytes beginning at buffer+20 would be sent. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 


The Data Message transmit queue for this logical link is full. NSP is waiting for 
acknowledgment from the remote system for previously sent Network Data Mes- 
sages. No more can be sent until at least or of the outstanding messages in the 
transmit queue is acknowledged. This condition is temporary and no Link Service 
Message notification occurs when the condition clears. The program should sim- 
ply retry the send after a short (1 to 5 second) delay. (See Chapter 4 for a full 
discussion of flow control.) 


5 CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


10 PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Network Data Message over a 
logical link that has not yet been confirmed will cause this error. 


18 ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The ula specified is zero. It must be within the range 1 to 255. 


(continued on next page) 
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errval Error Text and Meaning 


19 DISK BLOCK IS INTERLOCKED 


Either the remote system has inhibited transmission on this link off because of a 
backpressure condition or there are no outstanding requests for segments or logi- 
cal messages from the remote program (assuming it requested segment or message 
flow control for the link). 


The program will be notified with a Link Service Message when the condition 
clears, as described in Chapter 4. 


31 ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 1 and the transmit maximum (tmax) established by the remote program 
or system in its Connect Initiate or Connect Confirm Message for this logical link. 


32 NO BUFFER SPACE AVAILABLE 
System buffers are not currently available to store this message. A later try may 
succeed. 

62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 


Example: 


The following example shows a variable-length send from a buffer area de- 
fined by a dynamic string. The LEN function returns the correct number of 
bytes for the length argument. The user link address is 20. The value for 
DMFLGS% identifies the message data as the sole segment of a logical mes- 
sage and requests the return of link status information. Note the use of MAP 
statements to allocate space for the buffer for the returned data. First, the 
buffer for returned data is set up as 40 bytes long. Next, a MAP is made with 
a useful format for returned link status information. (Other maps of the same 
area would presumably be made for other message types. They are not shown 
here since we are concerned only with returned link status.) After the call, the 
program checks for an error. If none occurred, the program checks to see if 
there are any pending messages. If so, the program branches to receive and 
process messages. If not, the program simply continues. Note the use of the 
ASCII function to get integer values for the returned data. 
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1000 MAP (RETBUF) AS = 40% & 
\MAP (RETBUF) FILL% sCODE$=1% sULAS=1%,FILL$=16%% & 
LSTATS$=1% +RSTATS$=1% »sLDRS=12% 18 
LIR$=1% +RDR$=1% sRIRS=1% sDTM$=1% sDTCS=1% sLTMS=1%) & 
LTC$=1% sMMAX$=1% sMCNTS=1% »MULAS=1% & 


\EOM%Z = 2% & 

\BOM%Z = 1% & 

\RLS% = 128% & 

\B$ = "DYNAMIC STRING SEND - LEN WILL RETURN LENGTH" & 


\ERRVALZ = O% & 

\ULAZ = 20% & 

\DMFLGS% = EOMZ+BOMZ+RLSZ% & 

\CALL NTDM BY REF(ERRVAL% +A$ »ULA% »DMFLGSZ +BS> & 
LEN(BS) 0%) & 

\IF ERRVAL% <> 0% THEN GOTO 1500 & 

\IF ASCII(MCNT$) > O THEN GOTO 4000 & 


+ 
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6.6.6 Send Interrupt Message (NTIN) (DECnet) 


The NTIN call transmits an Interrupt Message to a remote program over an 
established logical link. All DECnet systems are designed to deliver Interrupt 
Messages ahead of other messages. If the remote system is a DECnet/E sys- 
tem, the Interrupt Message will be placed at the head of the pending message 
queue, behind the first message (since it can already be partly received) and 
behind any other pending Interrupt Messages queued for the program. Inter- 
rupt Messages are subject to flow control, as described in Chapter 4. 


BASIC-PLUS-2 Call Format: 
CALL NTIN BY REF(errval%,retbuf? ,ula%,inflgs%, buffer?, 
buflen%, bufoff%) 
Argument Descriptions: 
errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTIN call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “‘Possible Errors” at the end of this section. 


retbuf 


This argument names the buffer to receive link status information returned by 
the call. This argument must be specified regardless of whether or not link 
status information is requested and should refer to a preallocated buffer at 
least 40 bytes long. 


ula 


The ula is an integer value giving the user link address (1 to 255) chosen by 
the calling program in the Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


inflgs 


The inflgs argument indicates whether link status information is to be re- 
turned to retbuf when the call has completed successfully. 


inflgs% = rls% 
where 


rls = 128 Link status information is returned. 
rls = 0O No link status information is returned. 


If link status information is requested, it is returned in the same format as a 
received Link Service Message (Section 6.7.7). The MAP statement is partic- 
ularly useful to allocate the buffer, as it both allocates the space for the 
information and allows the definition of named fields with different data 
types within the buffer (see Section 6.1.1). 


If no link status information is requested, random data is returned. 
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buffer 


This argument defines the starting address of a buffer containing optional 
user message data. (See Section 6.1.1 for information on how to set up a buffer 
in BASIC-PLUS-2.) If a nonzero offset is given (see bufoff), the offset is 
added to the starting address of the buffer to determine where the data be- 
gins. 


buflen 
This integer value defines the number of bytes of user data to be sent: 0 to 16. 
bufoff 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufoff is added to the starting 
address of the buffer to define the beginning address user message data. For 
example, if bufoff = 20, the user data begins in byte 21 of the buffer. 


byte 1 20| 21 (buflen+20) 


user data 





whole buffer 


NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 16 and a bufoff 
of -100. Sixteen bytes beginning at buffer-100 would be sent. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 


The Interrupt/Link Service transmit queue for this logical link is full. NSP is 
waiting for acknowledgment from the remote system for previously sent Inter- 
rupt or Link Service Messages. No Interrupt or Link Service Messages can be 
sent until at least one of the outstanding messages in the transmit queue is 
acknowledged. This condition is temporary and no Link Service Message notifi- 
cation occurs when the condition clears. The program should simply retry the 
send after a short (1 to 5 second) delay. (See Chapter 4 for a full discussion of 
flow control.) 


5 CAN’T FIND FILE OR ACCOUNT 


The local link address (/la) does not correspond to any known logical link for the 
calling program. Either the lla is incorrect or the originating connect request has 
been cancelled. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


(continued on next page) 
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errval 


10 


18 


19 


31 


32 


62 


Example: 


The following example shows a NTIN call for logical link 15. The call sends 
the message data ““TIMEOUT” and requests no link status information to be 
returned. A buffer must be defined and referenced, however, so a MAP is set 
up with the string name DUMMY$ for reference in this case. (The same 
buffer area can be used with different mappings for other calls. The name 
DUMMY$ documents that the data returned is random and not used by the 


Error Text and Meaning 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending an Interrupt Message over a logical 
link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The user link address (ula) given was zero. Valid values range from 1 to 255. 
DISK BLOCK IS INTERLOCKED 


The remote NSP has prohibited transmission of Interrupt Messages over this 
logical link according to its rules for Interrupt Message flow control. A link 
Service Message will be delivered to the program when the condition clears. (See 
Chapter 4 for a full discussion of flow control.) 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 bytes for an Interrupt. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


program.) 
1000 MAP (RETBUF) DUMMYS = 4OZ & 
\ERRVAL% = O% & 
\AS = "TIMEOUT" & 
\BUFLEN% = LEN(AS$) & 
\OFFSET%Z = O% & 
\INFLGS = O% & 
\ULAZ = 15% & 
\CALL NTIN BY REF(ERRVAL% +DUMMY$ »ULA%+INFLGS%> & 


AG, 


BUFLEN% »BUFOFF%) 
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6.6.7 Send Link Service Message (NTLS) (DECnet) 


The NTLS call is used to: (1) request data from a remote program over a flow- 
controlled logical link (Chapter 4); (2) reenable incoming interrupts over a 
logical link (Chapter 4); or (3) obtain status information for the link. No user 
data is allowed with a Link Service Message. 


BASIC-PLUS-2 Call Format: 
CALL NTLS BY REF(errval%,retbuf? ,ula%, lsflgs%,drent%,ircnt%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTLS call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


retbuf 


This argument names the buffer to receive link status information returned by 
the call. The argument must be specified regardless of whether or not link 
status information is requested and should refer to a preallocated buffer at 
least 40 bytes long. 


ula 


The ula is an integer value giving the user link address (1 to 255) chosen by 
the calling program in the Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


Isflgs 


The link service flags argument is coded as the sum of two values: Isflgs% = 
rls% + opr%. The low-order two bits (opr) indicate the purpose of the call. 


opr =0 Indicates the call is requesting segments or logical messages from 
the remote program. In this case, the drcnt argument is interpreted 
as the number of segments or logical messages being requested. 
This form of the call can be used only when the calling program 
requested message or segment flow control in its Connect Initiate or 
Connect Confirm Message for the logical link. If no flow control was 
requested, an NTLS call with opr = 0 will fail, returning errval = 
18. 


=1 Indicates the call is to reenable incoming Interrupt Messages for 
this link. In this case, the ircnt argument is interpreted as the 
number of Interrupt Messages requested (always 1). 


—2 Indicates the call is to obtain status information only. In this case, 
the drcnt and ircnt arguments are ignored. 
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The rls bit can be used when opr = 0 or 1 to request that link status informa- 
tion be returned to the return buffer (defined by retbuf) when the call com- 
pletes successfully. 


rls = 128 Link status information is returned. 
rls = 0 No link status information is returned. 


Link status information is always returned when opr = 2. If requested, the 
information returned is in the same format as a received Link Service Mes- 
sage (Section 6.7.7) The MAP statement is particularly useful to define the 
buffer, as it both allocates the space for the information and allows the defini- 
tion of named fields with different data types within the buffer (see Section 
6.1.1). 


If no link status information is requested, random data is returned. 


drent 


The data request count (drcnt) is meaningful only when opr = 0 and indicates 
the maximum number of segments or logical messages being requested from 
the remote program. Depending on the flow control option in effect for the 
logical link, the value is interpretted as either a segment counter (segment 
flow control) or a logical message counter (message flow control). In either 
case, it is an incremental count, added to the counter of outstanding requests 
kept by the remote and local NSP (see Chapter 4). An error is returned if the 
drent given increases the counter to more than 127. 


ircnt 


The interrupt request count (ircnt) is meaningful only when opr = 1 and 
indicates the number of Interrupt Messages being requested. DECnet/E al- 
lows only one interrupt request outstanding for a logical link at any given 
time. Hence, ircnt must always be 1 when opr = 1 and has the effect of 
reenabling interrupts on the logical link. Remember that interrupts can be 
reenabled only when the previous Interrupt Message for this logical link, if 
any, has been received from the pending message queue. If it has not, the call 
will fail with an error (errval = 19). 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 


The Interrupt/Link Service transmit queue for this logical link is full. NSP is 
waiting for acknowledgment from the remote system for previously sent Interrupt 
or Link Service Messages. No Interrupt or Link Service Messages can be sent 


(continued on next page) 
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errval 


10 


18 


19 


32 


62 


Error Text and Meaning 


until at least one of the outstanding messages in the transmit queue is acknowl- 
edged. This condition is temporary and will not cause a Link Service Message to 
be queued when the condition clears. The program should simply retry the send 
after a short delay of 1 to 5 seconds. (See Chapter 4 for a full discussion of flow 
control.) 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Link Service Message over a 
logical link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of several possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The opr value is not 0, 1, or 2. 


3. The opr value is 0, but the calling program did not request flow control for the 
logical link in its Connect Initiate (NTCI) or Connect Confirm (NTCC) Mes- 
sage. 


4. The data request count (drent) increased the count of outstanding requests to 
more than 127. 


5. The opr value is 1, indicating a request for an Interrupt Message, but the ircnt 
argument does not equal 1. 


6. The opr value is 1, indicating a request for an Interrupt Message, but the 
outstanding requests counter for interrupts already equals 1. 


7. The ula specified is zero. It must be within the range 1 to 255. 
DISK BLOCK IS INTERLOCKED 


The opr value is 1, indicating a request for an Interrupt Message, but there is 
already one queued for this logical link. See Chapter 4 for details on flow control. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions can- 
not be executed. 
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Example: 


This example of the NTLS call requests five segments from the remote pro- ' ) 
gram over logical link 23. (Assume that the local program requested segment 
flow control in its NTCI or NTCC call for this link). 


1000 MAP (RETBUF) AS = 40% & 
NOPR%Z = O% & 
\RLS% = 128% & 


e 


NERRVAL% = O% & 

\ULAZ = 23% & 

\LSFLGS% = RLSZ+OPR% & 

\DRCNT%Z = 5% & 

\CALL NTLS BY REF(ERRVAL% +A% »ULA% +LSFLGS% »DRCNT% 10%) & 
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6.6.8 Send Disconnect Message (NTDI) (DECnet) 


The NTDI call is used to terminate an established logical link. Messages in 
the pending message queue will remain but no more messages can be sent over 
the link. The user link address is freed and can be used for another logical 
link. If the last Network Data Message sent did not have the end-of-message 
flag set, or if any Network Data, Interrupt, or Link Service Messages are still 
waiting for acknowledgment in the transmit queues for this logical link, this 
call will fail with an error. 


Successful completion of an NTDI assures the sender that the remote system 
has received and acknowledged all Network Data, Interrupt, and Link Service 
Messages previously sent over the link. It does not guarantee that the receiv- 
ing program has processed the messages, however. The Disconnect Message is 
useful in “master-slave” communication where the master program only 
transmits data and the slave program only receives data (see Section 3.13). 
Otherwise, the NTDI provides no particular advantage over an NTLA (Sec- 
tion 6.6.9) in terminating a logical link. 


Up to 16 bytes of user data can be passed with the Disconnect Message. 
BASIC-PLUS-2 Call Format: 
CALL NTDI BY REF(errval%,ula%, buffer? ,buflen%, bufoff%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTDI call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘Possible Errors” at the end of this section. 


ula 

The ula is an integer value giving the user link address (1 to 255) chosen by 
the calling program in the Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


buffer 


This argument defines the starting address of a buffer containing the optional 
user message data. (See Section 6.1.1 for information on how to set up buffers 
in BASIC-PLUS-2.) If a nonzero offset is given (see bufoff), the offset is 
added to the starting address of the buffer. 


buflen 

This integer argument defines the number of bytes of user data to be sent: 0 to 
16. 

bufoff 


This integer value defines an offset, from the beginning of the buffer specified 
by the buffer argument. The value of bufoff is added to the starting address of 
the buffer to define the beginning address of the user message data. For 
example, if bufoff = 20, the user data begins in byte 21 of the buffer. 
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byte 1 20 | 21 (buflen+20) 


whole buffer 





NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. If, for 
example, a program’s buffer is 20 bytes long, with an offset of 
10 and a buflen of 16, 16 bytes will be sent: the last 10 bytes of 
the buffer, and 6 bytes of whatever is beyond the buffer in 
memory. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 


There are outstanding unacknowledged messages on either the Data Message 
transmit queue or the Interrupt/Link Service transmit queue. All messages previ- 
ously sent over the logical link must be acknowledged before the Disconnect 
Message can be sent. (If an immediate unconditional termination of the logical 
link is desired, use the NTLA call.) 


5 CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


10 PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Disconnect Message over a logical 
link that has not yet been confirmed will cause this error. 


18 ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The ula specified is zero. It must be within the range 1 to 255. 


(continued on next page) 
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errval 


19 


31 


32 


62 


Example: 


Error Text and Meaning 
DISK BLOCK IS INTERLOCKED 


The last segment sent over this logical link did not have the eom flag set. NSP will 
not permit the link to be disconnected unless all messages have been completely 
transmitted. (Note that this test for the eom flag is done regardless of the flow 
control option chosen by the remote program.) 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. 'The length of the buffer must be 
between 0 and 16 for a Disconnect Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


The following example disconnects logical link 255 and includes user data 
explaining the reason for the disconnect. (The remote program would have to 
be coded to recognize this message and take appropriate action.) 


\ ULAZ 
\ ERRVAL% 


255% & 


= O% & 


\ CALL NTDI BY REF(CERRVAL% »ULAZ +"NOMORE" 16% 10%) 
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6.6.9 Send Link Abort Message (NTLA) (DECnet) 


The NTLA call is used to terminate a logical link immediately. If there are 
still messages in the transmit queues waiting for acknowledgment from the 
remote NSP, they are discarded. They may or may not have been received by 
the remote system (see Section 3.14). 


Up to 16 bytes of user data can be sent with the message. If the NTLA is 
issued for an established logical link, the remote system is notified that the 
link has been broken and the user data is delivered to the remote program. If 
the NTLA is issued for a logical link awaiting confirmation from the remote 
program, the user data does not reach the remote program (see Section 3.14). 


BASIC-PLUS-2 Call Format: 
CALL NTLA BY REF(errval%,ula%, buffer? buflen%, bufoff%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTLA call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


ula 


The ula is an integer value giving the user link address (1 to 255) chosen by 
the calling program in the Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


buffer 


This argument defines the starting address of a buffer where the optional user 
message data begins. (See Section 6.1.1 for information on how to set up 
buffers in BASIC-PLUS-2.) If a nonzero offset is given (see bufoff), the offset 
is added to the starting address defined by the buffer argument. 


buflen 
This integer value defines the number of bytes of user data to be sent: 0 to 16. 
bufoff 


This integer value defines an offset, in bytes, from the address specified by the 
buffer argument. The value of bufoff is added to the starting address of the 
buffer to find the beginning address of the user message data. For example, if 
bufoff = 20, the user data begins in byte 21 of the buffer. 


byte 1 20 | 21 (buflen+20) 


whole buffer 
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NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 16 and a bufoff 


of - 


100. Sixteen bytes beginning at buffer-100 would be sent. 


Possible Errors: 


errval 


18 


31 


32 


62 


Example: 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The ula specified is zero. It must be within the range 1 to 255. 
ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 for a Link Abort Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


The following example aborts logical link 17. No user data is sent. 


1000 MAP 


(BUFFER) AS = 256% & 


¢ 


NERRVALZ = O% & 
\CALL NTLA BY REF(ERRVALZ 117% +AG 10% 10%) 
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6.7 Receive (MRCV) (Local and DECnet) 
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The MRCV call is used to retrieve a message from the calling program’s 
pending message queue. It returns control parameters and user data, if any, to 
buffers defined in the call. The Connect Data Block for Connect Initiate 
Messages is also delivered to the buffer that receives the user data. The 
message data can be retrieved all at once or in portions, and portions can be 
discarded. The formats in Sections 6.7.1 - 6.7.9 show what control information 
is returned for the various types of messages. 


A Receive call can be selected to get (1) the first message in the queue, (2) the 
first message in the queue from either a network or a local sender, or (3) the 
first message in the queue for a particular logical link. A “sleep” flag and 
associated timer can be set to indicate that the calling program is to wait if 
there are no appropriate messages pending in the queue. 


BASIC-PLUS-2 Call Format: 


CALL MRCV BY REF(errval%,retbuf? ,rmod%,sndr%,qual%, buffer?, 
buflen%, bufoff%,slptime%) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MRCV call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘“‘Possible Errors” at the end of this section. 


retbuf 


This argument names the buffer to contain the control information identi- 
fying the type and characteristics of the message received. This argument 
must refer to a predefined buffer at least 40 bytes long. The MAP statement is 
particularly useful to define the buffer, as it both allocates the space for the 
returned information and allows the definition of named fields with different 
data types within the buffer (Section 6.1.1). The format of the data returned 
depends on the message type, as described in Sections 6.7.1 — 6.7.9. 


rmod 


The receive modifier (rmod) argument is an integer value consisting of four 
flags: s% + t% + 1% +n%. 


s The sleep flag (s) defines what is to be done if there is no appropriate 
message in the queue for the Receive call to deliver — that is, a message of 
the type requested with the |, n, sndr, and qual arguments. If s = 1, the 
program will “sleep,”’ suspending execution until something happens. The 
slptime argument regulates the time that the program will sleep. 
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If the s flag is set to 0, the program will not sleep. If there are no appro- 
priate messages in the queue the call terminates immediately with errval 


t The truncate flag (t) is set to 2 to discard any excess information that will 
not fit in the buffer specified in this call. Information could be left over if 
the value of buflen is smaller than the amount of user data in the message. 


A 0 value for t indicates that such excess information is to be kept for 
retrieval on later Receive calls. 


| The local sender flag (J) is set to 4 to select a message from a local sender. 
The selection can be further qualified with the sndr and qual arguments. 


If 1 = 0, local selection is not requested. If both / and n are zero, the first 
message in the queue is returned. 


n_ The network sender flag (n) is set to 8 to select a message from a network 
sender. The selection can be further qualified with the sndr and qual 
arguments. 


If n = 0, network selection is not requested. If both / and n = 0, the first 
message pending in the queue is returned. If / = 4 andn = 8, local selection 
prevails. 


sndr 


The sender selection argument (sndr) selects a particular local sender or a 
particular logical link for this Receive call. 


If | = 4 (local selection) and sndr is nonzero, sndr is interpreted as a job 
number times two. The first message on the queue from that particular local 
job is retrieved. 


If | = 0 and n = 8 (network selection), a nonzero value for sndr is interpreted as 
a user link address. The first message on the queue from that logical link is 
delivered. 


If sndr = 0 when either / = 4 or n = 8, the qual parameter has special meaning. 
The sndr and qual arguments are ignored if both / and n are zero. 


qual 


The sender selection qualifier (qual) argument is normally zero for user appli- 
cations. 


If | = 4 (local selection) and sndr = 0, then any nonzero value for qual is a 
special-case Receive call requesting a message from the system (job number 
0). This special case is used by the RSTS/E utility ERRCPY, which processes 
messages from the monitor error logging routines. 


The qual argument is ignored if both / and n = 0, or if sndr # 0. 


Table 6-4 summarizes the relationships between the selection bits of rmod 
and the sndr and qual arguments. 
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Table 6-4: Sender Selection Summary 


rmod 
n J sndr qual Result 


0 0 n/a n/a The sndr and qual values are ignored. The MRCV 
call returns the first message in the pending message 
queue. 


n/a 4 0 0 Selects the first Local Data Message in the queue. 


0 nonzero Selects job 0. This combination is used by the error 
logging programs to select messages from monitor 
error logging routines. 


nonzero n/a Selects Local Data Messages by job number. The 
sndr argument is interpreted as a job number times 2. 
Only messages from that job are delivered on this 
MRCV call. 


8 0 0 n/a Selects the first network message (anything other 
than a Local Data Message). 


nonzero n/a Selects network messages from a particular logical 
link. The sndr argument is interpreted as a user link 
address. Only network messages from the designated 
logical link are delivered on this MRCV call. 


buffer 


This argument defines the starting address of the buffer to which user mes- 
sage data is to be delivered. (See Section 6.1.1 for a discussion of how to set up 
buffers in BASIC-PLUS-2.) If a nonzero offset is given (see bufoff), the offset 
is added to the starting address defined by the buffer argument. 


buflen 


This integer argument defines the maximum number of bytes to be delivered 
to the buffer on this Receive call. 


If a program has limited buffer space, the buflen value can be set to process a 
large segment in small pieces. If truncation is not requested (t flag of rmod = 
0) and the amount of data in the message is greater than the amount indi- 
cated by buflen, then only the amount indicated by buflen will be returned 
and the rest will be saved for retrieval with later Receive calls. 


The usual sequence in this case is to issue Receive calls until the number of 
bytes remaining in the pending message goes to zero. This point can be deter- 
mined by examining bytes 9-10 in the data returned to the retbuf buffer by 
the Receive call. The number of bytes actually returned to the buffer is re- 
turned in bytes 13-14 in the retbuf buffer. (See the formats in Sections 6.7.1 — 
6.7.9.) 


bufoff 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufoff is added to the starting 
buffer address to define the beginning address of the user message data. For 
example, if bufoff = 20, the user message data is delivered beginning in byte 
21 of the buffer. 
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byte 1 20; 21 (buflen+20) 


whole buffer 
NOTE 


The BASIC-PLUS-2 interface makes no checks for inconsis- 
tencies in the buffer, buflen, and bufoff values specified. A 
program could, for example, specify a buflen of 100 and a bufoff 
of 20. Up to 100 bytes beginning at buffer+20 could be delivered 
on the Receive call. 


siptime 


The siptime argument is significant only when the s flag of rmod = 1. In that 
case, a positive value for slptime defines the length of time, in seconds, that a 
program is to sleep when no appropriate message is in the queue. The program 
will sleep until: 


The sleep timer expires. 


Any new message is placed in the queue (not just an appropriate one). 


1 

2 

3. A delimiter is typed on a terminal opened by, or assigned to, the job. 
4. Log-ins are disabled. (This could occur if the system is being shut down). 
5 


A state change occurs on a pseudo-keyboard assigned to the job. (The job 
has printed output for the controlling job to read or has entered an input 
wait state.) 


6. The job itself has opened the XM: (DMC11-driver) and a message is 
received for the job. 


In all cases, the program is awakened with an error (errval = 5) but is not 
passed a message. To obtain a pending message the program must execute 
another Receive call. Since the program can be awakened by any of the 
conditions listed previously, a check for pending messages can be made by 
executing a MRCV without a sleep. 


Possible Errors: 


errval Error Text and Meaning 


5 CAN’T FIND FILE OR ACCOUNT 


For a Receive call without sleep (s flag in rmod = 0), this error indicates that no 
appropriate messages are pending. For a Receive call with sleep (s flag in rmod = 
1), this error is returned when the program is awakened from the sleep. The 
program must execute another MRCV to retrieve any pending messages. 


18 ILLEGAL SYS() USAGE 


No Receiver ID Block exists for the calling program. Before any Receive call can 
succeed, a Declare Receiver (MDCL) call must be executed. 


Network Programming in BASIC-PLUS-2 6-55 


Example: 


In the following example, the first Receive call is issued for network messages, 
with the sleep bit set and the timer set to five seconds. The truncate bit is 0 
and the length argument is 0, so all the information that is available is saved 
for the second Receive call. (The test for ERRVAL% = 5% after the first 
Receive call, with sleep, ensures that a message is waiting when the second 
Receive call is issued.) 
1000 MAP (RET) RETBUF$ = 40% 

\MAP (BUF) BUFFERS = 256% & 

\S% = 1% & 

\N% = B% & 


+ 


nou 


+ 


NERRVALZ = O% & 

\NRMODZ = SZ+NZ & 

\NSLPTIMZ = 5% & 

2000 \CALL MRCY BY REF(ERRVAL% »RETBUFS$ »+RMOD% 10% +0%% & 

BUFFERS +0%sOZ%s+SLPTIMZ) & 

\IF ERRVAL%Z = 5% THEN GOTO 2000 & 

NRMODZ = N% & 

\CALL MRCY BY REF(CERRVAL% »sRETBUFS sRMODZ 10% +0%% & 
BUFFERS +256% 10% 10%) 


6-56 Network Programming in BASIC-PLUS and BASIC-PLUS-2 





6.7.1 Format of Received Local Data Message 


The format of the information returned to the retbuf buffer for a Local Data 
Message is shown below. Up to 512 bytes of user data can be delivered to the 
data buffer specified in the Receive (MRCV) call. 


Bytes Value Description 

1-2 _— Not meaningful - should be ignored. 

3 -1% The function code for a Local Data Message. 

4 Jobx2% Two times the job number of the local sender. 

5-6 ppn% The project-programmer number of the local sender. Byte 5 

= programmer number; byte 6 = project number. 
7-8 — Not meaningful — should be ignored. 
9-10 remainder% The number of bytes of user data not delivered to the 


buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t flag was set in 
the rmod argument in the MRCV call. 


11-12 _— Not meaningful - should be ignored. 

13-14 length% The number of bytes of user data transferred to the buffer 
on this Receive call. 

15-20 — Not meaningful - should be ignored. 

21-40 param$ The data passed as parameters by the sender of this mes- 


sage. The system pads any unused bytes with binary zeros 
to a length of 20 bytes. 


Sample MAP: 


MAP (RETBUF) AS = 40% 
MAP (RETBUF) FILL%+CODE$=1% +JOBX2$=1% »PROJ$=1% sPROGS=1% +FILLA%» & 
REMAINDER4 +FILL% +LGT% »FILL$=6% »PARAM$=20% 
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6.7.2 Format of Received Connect Initiate Message 


The format of the information returned to the retbuf buffer for a received 
Connect Initiate Message is shown below. A 120-byte Connect Data Block and 
up to 16 bytes of user data are also returned to the data buffer specified in the 
Receive call. The format of a received Connect Data Block is shown in Figure 
6-2 and described in detail in Table 6-5. 


Bytes 


1-2 


24 
25-26 


27-28 


29-40 
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Value 


remainder% 


rmax% 


tmax% 


Description 


Not meaningful - should be ignored. 
The function code for a Connect Initiate Message. 
Not meaningful - should be ignored. 


Local link address. Identifies the link for the local pro- 
gram’s subsequent Connect Confirm or Connect Reject 
Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not: delivered to the 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the buffer 
on this Receive call. 


Not meaningful - should be ignored. 


Remote link modifier. Indicates the flow control in effect for 
the remote program. The low-order two bits should be 
masked and interpretted as follows: 


flow% = rlmod% AND 3% 


If flow = 0, no flow control 
= 1, segment flow control 
= 2, message flow control 


Not meaningful - should be ignored. 


Receive maximum, in bytes. The maximum amount of user 
data that will be transmitted to the local program in one 
Network Data Message over this link. This value is sup- 
plied by the local NSP and is determined by the size of the 
receive buffers it allocates. The size of the receive buffers is 
set for NSP by Network Management. The local program 
can further limit the amount of user data to be received by 
specifying a smaller rmax in the Connect Confirm Message 
that accepts this request for a logical link (see Section 
6.6.3). 


Transmit maximum, in bytes. The maximum amount of 
user data that can be transmitted by the program in one 
Network Data Message over this link. This limit has been 
imposed by either the remote program or by the remote 
NSP. The local NSP enforces this limit for all Network 
Data Messages sent by the local program on this link. 


Not meaningful - should be ignored. 
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Sample MAP: 


MAP (RETBUF) AS = 40 


MAP (RETBUF) FILL%sCODES=1% sFILL$=1% sLLAZ+FILL%Z+REMAINDERZ:+ & 
FILL%+LGT% +FILL$=8% sRLMOD$=1% +FILLS=1% s+RMAKZ + TMAXKS 







(7) (8) (9) (10) (11) (22) (23) (26 
27 | 28 | 29 | 30 | 31 42/43 46 


we. fe DESCRIPTOR 


Po[efofo] == | 
Pe fofols| mon | 
EN ee ae 


LL. 


for local program name 








DECnetv/E accepts Connect Initiate 
Messages addressed to object type 
code or name — not both 


LEN = length of descriptor 
format 

object code 

number 


length 


REMOTE | REMOTE LOCAL ACCESS CONTROL FIELDS RESERVED 
NODE PROGRAM PROGRAM 


461} 47 






47 | 48 | 49 64} 65 | 66 {67 74] 75] 76 | 77 92 


& L ACCOUNTING 
0 Jen! USERID [0 [| password | Eyl INFORMATION 


supply if needed by remote program 


Figure 6-2: Format of Received Connect Data Block 


Table 6-5: Format of Received Connect Data Block 


Bytes Content 


1-6 Remote Node. 1 to 6 uppercase, alphanumeric ASCII characters naming the 
remote node from which the Connect Initiate Message was received. The name 
will contain at least one alphabetic character. Node names shorter than six 
characters will be left-justified and padded to six characters with spaces. 


7-26 Remote Program. Identifies the remote program that sent the Connect Initiate 
Message as either an object type (general function) or a specific entity (program, 
task, or process) This identification is given in one of three formats: 


Format 0 


The remote program is identified by object type code alone. The fields are: 


Bytes Content 


7 Zero, to indicate a format 0 name. 
8 Object type code of the remote program. 
9-26 Not meaningful - should be ignored. 


(continued on next page) 
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Table 6-5 (Cont.): Format of Received Connect Data Block 


Format 1 


The remote program is identified by a descriptor. The fields are: 


Bytes Content 


7 One, to indicate a format 1 name. 

8 Normally zero. This byte will usually be zero unless the remote DEC- 
net system allows identification by both name and object type code on 
outgoing connect requests (DECnet/E does not). If nonzero, this byte is 
interpreted as the object type code of the remote program that sent the 
Connect Initiate Message. 


9 Not meaningful - should be ignored. 

10 Length of descriptor, 0 to 16 bytes. Gives the number of characters to 
be interpreted as the program descriptor in the following field (bytes 
11-26). 


11-26 Remote program descriptor (left-justified). The descriptor used to reg- 
ister the remote program for network operations. For remote DECnet/E 
systems, this is the logical name declared in the Declare Receiver call. 


Format 2 


This format identifies the remote program by name or object type code and by 
the group and user codes under which the remote program is running on the 
remote system. (The group and user codes refer to what is called the project- 
programmer number on some DIGITAL systems, including RSTS/E. Other sys- 
tems refer to these codes as the user identification code, or UIC.) DECnet/E 
systems use this format to identify the sender of a Connect Initiate Message. 


The subfields are defined as follows: 


Bytes Content 


7 Two, to indicate a format 2 name. 

8 Object type code of the remote program, if applicable. If zero, the 
descriptor alone identifies the remote program. 

9 Not meaningful - should be ignored. 

10 Length of descriptor, 0 to 12 bytes. Gives the number of characters to 
be interpreted as the program descriptor in the following field (bytes 
11-22). 


11-22 Remote program descriptor, if this is used instead of object type code. 
The descriptor will be left-justified in the field. 

23-24 Remote group code. Binary value giving the group number under which 
the remote program is running. If the remote system is a DECnet/E 
system, byte 23 is the project number in a project-programmer number. 

25-26 Remote user code. Binary value giving the user number under which 
the remote program is running. If the remote system is a DECnet/E 
system, byte 25 is the programmer number in a project-programmer 
number. 


(continued on next page) 
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Table 6-5 (Cont.): Format of Received Connect Data Block 


27-46 


47-92 


Local Program. This field indicates how the remote program addressed the 
local program in the Connect Initiate Message. DECnet/E allows the local pro- 
gram to be addressed by object type code or by name, but not both. Again, three 
formats can be used. The subfields are as follows: 


Bytes Content 


27 Format type. Equal to 0, 1, or 2, depending on the format used by the 
remote program to address the local program. 

28 Object type code, if used by the remote program to address the local 
program (formats 0 or 2). 

29 Always zero. 

30 Length of name, in bytes. Will be 0 for format 0, 1 to 6 for format 1, 0 to 


6 for format 2. (DECnet/E program names are limited to a maximum of 
six characters by the Declare Receiver call.) 

31-36 Local program name, if used by the remote program to address the 
local program (formats 1 or 2). 

37-42 Always zero. 

43-44 Local group code. Binary value giving the local program’s project num- 
ber, if used by the remote program to address the local program (for- 
mat 2). Zero otherwise (formats 0 or 1). Not used by NSP to identify 
the local program but passed on here. 

45-46 Local user code. Binary value giving the local program’s programmer 
number, if used by the remote program to address the local program 
(format 2). Zero otherwise (formats 0 or 1). Not used by NSP to iden- 
tify the local program but passed on here. 


Access Control Fields. These bytes can be used to define the remote program’s 
access rights to the local program’s services. The idea is analogous to logging in 
to the local system. The most rigorous checking done in a normal log-in on 
DIGITAL systems involve user identification, password, and account number, so 
three fields are defined here for those items. However, overall DECnet design 
does not specifically require use of these fields at all nor does it require that the 
fields be used as described. A DECnet/E system simply passes this information 
on to the receiving program. 


Bytes Content 


47 Not meaningful - should be ignored. 
48 Length of user identification information specified in the next field, 0 
to 16 bytes. 


49-64 User Identification. This field identifies the person or program request- 
ing the logical link. In RSTS/E terms, the user ID is analogous to the 
project-programmer number used at log-in. 

65 Not meaningful - should be ignored. 

66 Length of password information specified in the next field, 0 to 8 bytes. 

67-74 Password. A password is often used to verify access to a system under a 
particular user identification. In RSTS/E, this password is analogous to 
the password used in conjunction with the project-programmer number 
at log-in. 


(continued on next page) 
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Table 6-5 (Cont.): Format of Received Connect Data Block 


Bytes Contents 


75 Not meaningful - should be ignored. 
76 Length of the accounting information specified in the following field, 0 
to 16 bytes. 


77-92 Accounting information. Many systems require a billing account num- 
ber in addition to user identification and password. The accounting 
field is provided for this purpose. 


93-120 Reserved for future use. Should be ignored. 


Sample MAP of Connect Data Block: 


MAP (CDB) A¥ e 120% 

MAP (CDB) REMNODES= 6%+REMFMT$=1% +REMOBJ$=1% & 
FILL$=1% +REMLEN$=1% »REMNAMES=12%) 8 
REMGRP$=1%+FILL$=1% sREMUSR#=1% sFILLS=1%% & 
LOCFMT$=1% sLOCOBJ$=1%;FILL$=1%+ & 
LOCLEN$=1%+LOCNAME$=12%, & 

LOCGRP$=1% sFILL$=1% »,LOCUSR$=1% sFILLS=1%5 & 
FILL$=1%,IDLGT$=1% sUSRID$=16%» & 
FILL$=1%+PWDLGT$=1% »PASSWRDS=8% > & 
FILL$=1% s-ACCTLGT$=1% sACCNT$=16% sFILL$=28% 
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6.7.3 Format of Received Connect Confirm Message 


A received Connect Confirm Message is a remote program’s acceptance of a 
Connect Initiate Message sent by the local program. The link is identified by 
the user link address specified by the local program in the Connect Initiate 
Message. The format of the information returned to the retbuf buffer is de- 
scribed below. Up to 16 bytes of user data can also be returned to the data 
buffer specified in the Receive call. 


Bytes 


1-2 


11-12 
13-14 


15-22 
23 


24 
25-26 


27-28 


29-40 


Value 


remainder% 


length% 


rlmod% 


rmax% 


tmax% 


Description 


Not meaningful - should be ignored. 
The function code for a Connect Confirm Message. 


User link address, previously defined by the local program 
in its Connect Initiate Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 


Remote link modifier. Indicates the flow control in effect for 
the remote program. The low-order two bits should be 
masked and interpretted as follows: 


flow% = rlmod% AND 3% 


If flow = 0, no flow control 
= 1, segment flow control 
= 2, message flow control 


Not meaningful - should be ignored. 


Receive maximum, in bytes. The maximum amount of user 
data that will be transmitted to the local program in one 
Network Data Message over this link. This will be (1) equal 
to the rmax value specified in the Connect Initiate Message 
for this link, or (2) a lesser value supplied by the local NSP, 
calculated from the size of the receive buffers it allocates. 


Transmit maximum, in bytes. The maximum amount of 
user data that can be transmitted by the local program in 
one Network Data Message over this link. This limit has 
been imposed by either the remote program or by the re- 
mote NSP. The local NSP enforces this limit for all Net- 
work Data Messages sent by the local program on this link. 


Not meaningful - should be ignored. 
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Sample MAP: 


MAP (RETBUF) AS = 40% 
MAP (RETBUF) FILL% sCODES=1% »;ULA$=1% sFILL$=4% »REMAINDERZ »FILL% + 
LGT%ZsFILL$=8% +RLMOD$=1% sFILLS=1% +RMAXZ + TMAX% 
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& 





6.7.4 Format of Received Connect Reject Message 


A received Connect Reject Message is a rejection of the local program’s re- 
quest for a logical link. It can be from the remote program or the local or 
remote NSP. The link is identified by the user link address previously estab- 
lished in the local program’s Connect Initiate Message. The format of the 
information returned to the retbuf buffer is described below. Rejections from 
NSP will contain a reason code explaining the reason for the rejection and will 
not contain user data. Rejections from the remote program can contain up to 
16 bytes of user data, delivered to the data buffer defined in the Receive call. 


Bytes 


1-2 


11-12 
13-14 


15-22 
23-24 
25-40 


Value 


remainder% 


length% 


reason% 


Sample Map: 


MAP (RETBUF) AS = 


MAP (RETBUF) 


Description 


Not meaningful - should be ignored. 
The function code for a Connect Confirm Message. 


User link address, previously defined in the local program’s 
Connect Initiate Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 
Identifies the reason for the rejection (see Appendix B). 


Not meaningful - should be ignored. 


FILL% sCODE$=1% »-ULA$=1% +FILL$=4% »sREMAINDERZ sFILLZ+ & 


LGT% »sFILL$=8% »+REASONZ 
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6.7.5 Format of Received Network Data Message 


A received Network Data Message contains user data from a remote program. 
The format of the information returned to the retbuf buffer is described be- 
low. The user data accompanying the Network Data Message is delivered to 
the data buffer specified in the Receive call. 


Bytes 


1-2 


22-40 


Value 


remainder% 


length% 


dmflgs% 


Sample MAP: 


MAP 
MAP 


(RETBUF) AS = 


40% 


Description 


Not meaningful - should be ignored. 
The function code for a Network Data Message. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t¢ flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 


Data message flags. Indicate whether this is the beginning, 
middle, end, or sole segment of a logical message. The low- 
order two bits should be masked and interpretted as fol- 
lows: 


bom% = dmflgs% AND 1% 
eom% = dmflgs% AND 2% 


Then 
eom bom 


0 0 Middle segment of message 
0 1 First segment of message 
2 0 Last segment of message 
2 1 Sole segment of message 


DECnet/E uses the eom bit to determine the end of a logi- 
cal message if the local program requested message flow 
control when the logical link was established. It does not 
use the bom bit but passes it on to the receiving program. 


Not meaningful - should be ignored. 


(RETBUF) FILL% »sCODE$=1% s;ULA$=1%sFILL$=4% sREMAINDERZ »FILL% + & 
LGT%Z»FILL$=6% sDMFLGS$=1% 
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6.7.6 Format of Received Interrupt Message 


The local NSP places Interrupt Messages from a remote program at the head 
of the pending message queue, behind the first message and behind any other 
pending Interrupt Messages queued for the program. The format of the data 
returned to the retbuf buffer is described below. Up to 16 bytes of user data 
can be delivered to the data buffer specified in the Receive call. 


Bytes 


1-2 
3 
4 


5-8 
9-10 


11-12 
13-14 


15-40 


Value 


remainder% 


length% 


Sample MAP: 


MAP 


(RETBUF) AS = 
MAP (RETBUF) 


Description 


Not meaningful - should be ignored. 
The function code for an Interrupt Message. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the buffer 
on this Receive call. 


Not meaningful - should be ignored. 


FILL% sCODES=1% +ULAS=1% sFILLS=4%5 & 


REMAINDERS »FILL% »+LGT% 
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6.7.7 Format of Received Link Service Message 


A Link Service Message provides status information for a particular logical 
link. A Link Service Message is only returned on a Receive call whenever the 
pending message queue has emptied after a condition has cleared that previ- 
ously inhibited the local program from sending (see Section 4.2). Status infor- 
mation with the same format as a Link Service Message can also be returned 
to the retbuf buffer on successful completion of a Send Link Service, Send 
Network Data, or Send Interrupt call. The format of the information returned 
is described below. No data is delivered to the data buffer with a Link Service 


Message. 
Bytes 


1-2 


Value 


lstat% 


Description 


Not meaningful - should be ignored. 
The function code for a Link Service Message. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


Always zero for Link Service Messages. (These bytes are 
the remainder field in other returned messages.) 


Not meaningful - should be ignored. 


Always zero for Link Service Messages. (These bytes are 
the length field in other returned messages.) 


Not meaningful - should be ignored. 


Local status flags. These flags should be masked and inter- 
pretted as follows: 


data% = lstat% AND 1% 
intls% = lstat% AND 2% 
Iclbp% = Istat% AND 192% (2-bit field) 


If data = 1, outgoing Network Data Messages are inhibited. 
(A Link Service Message will be delivered when the condi- 
tion clears.) 


If intls = 2, outgoing Interrupt and Link Service Messages 
are inhibited. (A Link Service Message will be delivered 
when the condition clears.) 


The Iclbp value indicates the local NSP’s backpressure 
status: 


0 Incoming Data Message flow is on. 


64 Incoming Data Message flow is on but the local NSP 
will turn this link off if another Data Message is 
received before the local program’s receive queue is 
emptied. 


128 Incoming Data Message flow has been turned off by 
the local NSP. The local program’s receive queue 
must be emptied before the link will be turned on. 


192 Incoming Data Message flow has been turned off by 
the local NSP but flow is scheduled to turn on as soon 
as system buffers become available. 


(continued on next page) 
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22 


23 


24 


25 


26 


27 


28 


29 


30 


31 


32 


33 


34-40 


rstat% 


ldr% 


lir% 


rdr% 


rir% 


dtm% 


dtc% 


ltm% 


ltc% 


mmax% 


Remote status flags. Only one bit is currently defined for 
this field. It should be masked and interpretted as follows: 


rembp% = rstat% AND 128% 


If rembp = 128, the link has been turned off by the remote 
system due to a backpressure condition. No Data Messages 
can be sent until the remote system turns the link back on. 


Local data request count. The count of segments or logical 
messages currently requested by the local program, reflect- 
ing the actual number of segments or logical messages re- 
quested but not yet received. 


Local interrupt request count. The count of Interrupt Mes- 
sages currently requested by the local program, reflecting 
the actual number of interrupts requested but not yet 
received. This count will never exceed one. 


Remote data request count. The count of segments or logi- 
cal messages currently requested by the remote program, 
reflecting the actual count of segments or messages re- 
quested but not yet sent. 


Remote interrupt request count. The count of Interrupt 
Messages currently requested by the remote end of the logi- 
cal link, reflecting the actual count of interrupts requested 
but not yet sent. 


Data transmit queue maximum. The maximum number of 
data messages that can be queued waiting for acknowledg- 
ment from the remote system. This is a constant set by the 
system manager when NSP is enabled. It applies individu- 
ally to all active logical links. 


Data transmit queue count. The number of data messages 
currently in the data transmit queue for this logical link. It 
is a count of data messages waiting for acknowledgment 
from the remote NSP. 


Interrupt/Link Service transmit queue maximum. The 
maximum number of Interrupt or Link Service Messages 
that can be queued waiting for acknowledgment from the 
remote system. This is a constant set by the system mana- 
ger when NSP is enabled. It applies individually to all ac- 
tive logical links. 


Interrupt/Link Service transmit queue count. The number 
of Interrupt and Link Service Messages currently in the 
Interrupt/Link Service transmit queue for this logical link. 
It is a count of Interrupt and Link Service Messages waiting 
for acknowledgment from the remote NSP. 


Message maximum. The maximum number of incoming 
messages that will be queued for the local program. This 
maximum is set by the local program in its Declare Re- 
ceiver call. 


Message count. The total number of messages currently in 
the pending message queue for the local program. 


Message count for this logical link. The number of mes- 
sages currently in the pending message queue for the logical 
link identified by the ula in byte 4. 


Not meaningful - should be ignored 
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Sample MAP: 


MAP (RETBUF) AS = 40% 

MAP (RETBUF) FILL%+CODE$=1% sULAS=1%,FILL$=16%) & 
LSTATS=1%sRSTATS$=1% +LDRZ=1Z%+LIRS=1%% & 
RDR#=1%sRIRS=1% sDTM$=1% sDTCH=1%5 & 
LTM$=1% sLTCS=1% sMMAXS=1%5 & 

MCNT$=1% »sMULAS=1% 
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6.7.8 Format of Received Disconnect Message 


A received Disconnect Message indicates that an established logical link with 
a remote program has been disconnected by the remote program. All other 
messages sent by the remote program over this logical link have been received 
by the local program. The format of the data returned to the retbuf buffer is 
defined below. Up to 16 bytes of user message data can be returned to the data 
buffer specified in the Receive call. 


Byte 


9-10 


11-12 
13-14 


15-40 


Value 


remainder% 


length% 


Sample MAP: 


MAP (RETBUF) AS = 


MAP (RETBUF) 


Description 


Not meaningful - should be ignored. 
The function code for a Disconnect Message. 


User link address, previously defined by the local program 
in its Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 


FILL% »sCODE$=1% sULAS=1% +FILLS=4%)5 & 


REMAINDERS +FILL%+LGT% 
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6.7.9 Format of Received Link Abort Message 


A received Link Abort Message indicates that a logical link has been termi- 
nated by the remote program or by the local or remote NSP. The format of the 
data returned to the retbuf buffer is defined below. Up to 16 bytes of user 
message data can be returned to the data buffer specified in the Receive call. 


Bytes 


1-2 
3 
4 


5-6 


7-8 
9-10 


11-12 
13-14 


15-22 
23-24 


25-40 


Value 


lla% 


remainder% 


length% 


reason% 


Sample MAP: 


MAP 
MAP 


(RETBUF) AS = 
(RETBUF ) 


Description 


Not meaningful - should be ignored. 
The function code for a Link Abort Message. 


User link address (if any), previously defined by the local 
program in its Connect Initiate or Connect Confirm Mes- 
sage. 


Local link address, established by the local NSP for this 
link. It identifies the link if the remote program sent a 
Connect Initiate Message but the local program has not yet 
responded with a Connect Confirm or Connect Reject Mes- 
sage. No ula exists under these conditions to identify the 
link being aborted. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the t flag was set in 
the rmod argument in the MRCV call. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 


Abort reason. If nonzero, the link was aborted by either the 
local or remote NSP and the reason is specified in these two 
bytes. The reasons that apply for a link abort are listed in 
Appendix B. If reason is zero, the link was aborted at the 
request of the remote program. 


Not meaningful - should be ignored. 


FILL% sCODES$=1% sULAS=1% +LLAZ»FILLA» & 


REMAINDERZ »sFILL%»LGT% sFILL$=8% sREASONZ 
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Appendix A 
Object Type Codes 


Code Type of Process 

000 General Task, User Process 

001 File Access (FAL/DAP Version 1) 

002 Unit Record Services (URD) 

003 Application Terminal Services (ATS) 

004 Command Terminal Services (CTS) 

005 RSX-11M Task Control, Version 1 

006 Operator Services Interface 

007 Node Resource Manager 

008 IBM 3270-BSC Gateway 

009 IBM 2780-BSC Gateway 

010 IBM 3790-SDLC Gateway 

011 TPS Application 

012 RT-11 DIBOL Application 

013 TOPS-20 Terminal Handler 

014 TOPS-20 Remote Spooler 

015 RSX-11M Task Control, Version 2 

016 TLK Utility (LSN on DECnet/E) 

017 File Access (FAL/DAP Version 4 and later) 
018 RSX-11S Remote Task Loader 

019 Network Management Listener (NICE Process) 
020 RSTS/E Media Transfer Program (NETCPY) 
021 Reserved for DECnet use 

022 Mail Listener 

023 Host Terminal Handler (NPKDVR) 

024 Concentrator Terminal Handler 


(continued on next page) 


025 Loopback Mirror 2) 


026 Event Receiver 

027 VAX/VMS Personal Message Utility 
028 File Transfer Spooler (FTS) 

029-062 Reserved for DECnet use 

063 DECnet test tool (DTR) 


064-127 Reserved for DECnet use 


128-255 Reserved for customer extensions 
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Appendix B 


NSP Reason Codes for Connect Reject 
and Link Abort 


Code 


024 
025-031 
032 
033 
034 
035 
036 


Reason 


No error - user-initiated reject or abort 

Resource allocation failure 

Destination node does not exist 

Node shutting down 

Destination program does not exist 

Invalid destination name or source name field 
Destination program’s queue full 

Unspecified error condition 

Third party aborted logical link 

User-initiated link abort 

Reserved 

Invalid destination address in Connect Initiate Message 
Invalid destination address in Connect Confirm Message 
Source address zero in Connect Initiate or Connect Confirm Message 
Flow control violation - invalid request count in Link Service Message 
Reserved 

Too many connects to node 

Too many connects to destination program 

Access not permitted 

Logical link services mismatch 

Invalid accounting information 


(continued on next page) 


B-1 


037 
038 
039 
040 
041 
042 
043 


Segment size too small 

User aborted, timed out, or canceled link 

No path to node 

Flow control failure - data received when request count zero 
No current link (cannot recognize destination address) 
Confirmation from remote system of Disconnect Message 


Image data field too long 
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Buffer ; 

: Data transmit queue, 4-9 to.4-11, 5-51, 5-55, 5-74, 
allocating (BASIC-PLUS), 5-2 6-47, 6-50 as 
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Buffer arguments (BASIC-PLUS-2), 6-3 to 6-4 
BUILD command, 6-4 
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message maximum, 3-4 
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sleep bit, 5-6 to 5-7, 6-7 

system call (BASIC-PLUS), 5-4 to 5-10 


c system call (BASIC-PLUS-2), 6-5 
Default project-programmer number, 3-5, 4-6, 5-12, 
Channel number, 5-2 6-12 
COM statement, 6-2 DEFINE OBJECT, 4-5 
COMPILE command, 6-4 Device, 
Compiling BASIC-PLUS-2 programs, 6-4 I/O channel, 5-2 
Connect Confirm Message, 3-8 to 3-9 — null device, 5-2 
received format (BASIC-PLUS), 5-69 opening, 5-2 
received format (BASIC-PLUS-2), 6-63 to 6-64 Device controllers, 1-5 
send call (BASIC-PLUS), 5-30 to 5-33 DIGITAL Data Communications Message Protocol 
send call (BASIC-PLUS-2), 6-28 to 6-31 See DDCMP 
Connect Data Block, 3-7, 3-8, 4-6, 5-24, 5-25, 5-66 DIGITAL Network Architecture, 
to 5-68, 6-22, 6-23 to 6-26, 6-59 to 6-62 See DNA 
Connect Initiate Message, 3-6 to 3-8 DIM statement, 6-2 
local program identification, 5-26 to 5-27, 5-67. ~—~dDiisconnect Message, 3-11 
to 5-68, 6-24 to 6-25, 6-61 affected by transmit queues, 4-10 
received format (BASIC PLUS), 5-65 to 5-68 received format (BASIC-PLUS), 5-76 
received format (BASIC PLUS-2), 6-58 to 6-62 received format (BASIC-PLUS-2), 6-71 
remote program identification, 5-25, 5-66 to send call (BASIC-PLUS), 5-51 to 5-54 
5-67, 6-23, 6-59 to 6-60 send call (BASIC-PLUS-2), 6-47 to 6-49 
send call (BASIC-PLUS), 5-22 to 5-29 DMx controllers, 1-5 
send call (BASIC-PLUS-2), 6-21 to 6-27 DNA, 1-2, 1-3, 3-6, 5-14, 6-14 


Hop, 1-2 

End node, 1-4 

ERRCPY, 5-60, 6-53 

Errors, l 
Declare Receiver, 5-9, 6-9 
Get Local Node Parameters, 5-13, 6-13 
Log User Event, 5-16 to 5-17, 6-16 
Receive, 5-62, 6-55 
Remove Receiver, 5-11, 6-11 


I/O channels, 5-2 

Interrupt Message, 2-7, 3-10 
queuing, 2-7, 3-10, 5-43, 5-72, 6-40, 6-67 
received format (BASIC-PLUS), 5-72 


pera Confirm Message, 5-32 to 5-33, received format (BASIC-PLUS-2), 6-67 
zs me reenabling, 3-10, 3-10, 4-16 
ares Initiate Message, 5-28 to 5-29, request count, 4-16, 5-48, 5-74, 6-44, 6-69 
a 0 O- : send call (BASIC-PLUS), 5-43 to 5-46 
ay ee ee send call (BASIC-PLUS-2), 6-40 to 6-42 


Interrupt Message flow control, 3-10, 4-16 


ae a Message, 5-52 to 5-53, effect on DECnet/E programs, 4-16 
o 6- 7 ‘ 
use of Link Service Message, 4-16 
Send Interrupt Message, 5-45 to 5-46, 6-42 Interrupt/Link Service queue, 4-9, 5-51, 5-55, 5-74, 
Send Link Abort Message, 5-56 to 5-57, 6-51 6-47, 6-50, 6-69 
Send Link Service Message, 5-49 to 5-50, Interrupts, 
6-44 to 6-45 See Interrupt Message 
Send Local Data Message, 5-20, 6-19 to 6-20 
Send Network Data Message, 5-41 to 5-42, J 
6-37 to 6-38 
Events, 
Job 
See U t ; 
oe determining number, 4-2 
killing, 4-5 
number in Receive, 5-60, 6-53 
F number of local receiver, 3-6, 5-19, 6-18 


privilege level, 4-6, 5-3 
Receiver ID Block, 3-5, 5-4, 6-5 
receiving from system job 0, 5-60, 6-53 


File Access Listener Remove Receiver, 3-5, 5-11, 6-11 


See NFT/FAL 
File Processor 

See FIP 
FIP, 5-1 K 
Flow control, 2-8, 3-10, 4-8 to 4-20 

backpressure, Killing a job, 4-5 

See Backpressure flow control 

Interrupt Message, 


See Interrupt Message flow control L 

local congestion, 4-18 

local modifier, 5-23 to 5-24, 5-31, 6-21, 6-28 Link, 

program-regulated, logical 

See Program-regulated flow control See Logical link 

programming hints, 4-18 to 4-20 physical 

reasons for inhibiting transmission, 4-18 See Physical link 

remote congestion, 4-18 Link Abort Message, 3-12 

remote modifier, 5-65, 5-69, 6-58, 6-63 received format (BASIC-PLUS), 5-77 

transmit queue management received format (BASIC-PLUS-2), 6-72 

See Transmit queue management send call (BASIC-PLUS), 5-55 to 5-57 

use of Link Service Message, 4-19 send call (BASIC-PLUS-2), 6-50 to 6-51 
Full duplex transmission, 2-3 unaffected by transmit queues, 4-10 
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Link master, 2-2 
Link Service Message, 3-10, 3-10 to 3-11 


purpose, 3-10, 4-12, 4-14, 4-16, 5-48, 5-73, 6-43, 


6-68 
received format (BASIC-PLUS), 5-73 to 5-75 


received format (BASIC-PLUS-2), 6-68 to 6-69 


send call (BASIC-PLUS), 5-47 to 5-50 
send call (BASIC-PLUS-2), 6-43 to 6-46 


Link status bit, 5-40, 5-44, 5-48, 6-36, 6-40, 6-44 


Link status flags, 
local, 5-73, 6-68 
remote, 5-74, 6-69 
Link status information, 5-73, 6-69 
Interrupt Message call, 3-10 
Link Service Message call, 3-10 
Linking BASIC-PLUS-2 programs, 6-4 
LLA, 2-3, 3-8, 3-9, 3-12, 5-31, 5-34, 6-28, 6-32 
Local communication, 3-1, 3-3, 3-6, 5-18, 6-18 
Local Data Message, 3-6 
received format (BASIC-PLUS), 5-64 
received format (BASIC-PLUS-2), 6-57 
send call (BASIC-PLUS), 5-18 to 5-21 
send call (BASIC-PLUS-2), 6-18 to 6-20 
Local link address, 
See LLA 
Local link status flags, 5-73, 6-68 
Local node, 1-1, 3-5 
Local node parameters, 3-2, 3-5, 4-6 
system call (BASIC-PLUS), 5-12, to 5-13 
system call (BASIC-PLUS-2), 6-12 to 6-13 
Local program, 3-3, 3-4 


identification, 5-26 to 5-27, 5-67 to 5-68, 6-24 


to 6-25, 6-61 


Log-in information, 3-6, 4-6, 5-27, 5-68, 6-25, 6-61 


Logical full duplex transmission, 2-3 
Logical link, 2-1 
aborting, 
See Link Abort Message 
accepting, 
See Connect Confirm Message 
active, 3-5, 3-5 
creating, 2-2 


declared maximum, 3-4, 4-2, 4-3, 5-6, 5-6, 5-8, 


6-7, 6-9 
declared message maximum, 3-4, 4-3, 5-8, 
5-75, 6-8, 6-69 
DECnet/E limitations, 2-8 
disconnecting, 
See Disconnect Message 
efficient line usage, 2-3 
identifiers, 2-2, 2-3 
message count, 5-75, 6-69 
message streams, 2-6 
receive maximum, 
See Receive maximum 
rejecting, 
See Connect Reject Message 
requesting 


See Connect Initiate Message 
transmit maximum, 
See Transmit maximum 
Logical message, 4-14, 5-39 to 5-40, 5-48, 5-71, 
6-35 to 6-36, 6-43, 6-66 
end of message segment, 4-15 
request count, 4-15, 5-48, 5-74, 6-44, 6-69 


MACRO-11 subroutines, 1-4 
MAP statement, 6-2, 6-44 
Master-slave communication, 3-11, 5-51, 6-47 
MDCL call, 
See Declare Receiver 
Message, 
count for logical link, 5-75, 6-69 
count of pending messages, 5-75, 6-69 
declared maximum, 3-4, 4-2, 4-3, 5-8, 5-75, 
6-8, 6-69 
limit of transmit queues, 4-10 
logical, 
See Logical message 
request count, 4-15 
Message flow control, 4-14 
Message streams, 2-5, 2-6, 3-10 
MRCYV call, 
See Receive 
MREM call, 
See Remove Receiver 
MSLD call, 
See Local Data Message 
Multiple copies of objects, 3-4, 4-2, 4-3 to 4-4 
under BATCH, 4-4 
via automatic startup, 4-4 
via terminal users, 4-3 to 4-4 
Multipoint lines, 1-5 


NCP, 1-5, 4-4, 4-10 

NET, 1-5 

NETCPY, 1-5, 4-12 

Network, 1-1, 1-2 

Network addressing, 3-3, 4-1 
declaring identity, 
See Receiver identity 
handling incoming requests, 4-2 
permitted by DECnet/E, 4-2 
to name, 4-3 
to object type code, 4-2 

Network Command Terminal Utility, 
See NET 

Network Communications Utility, 
See TLK/LSN 
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Network Control Program, 
See NCP 
Network Copy Utility, 
See NETCPY 
Network Data Message, 3-9 to 3-10 
received format (BASIC-PLUS), 5-71 
received format (BASIC-PLUS-2), 6-66 
send call (BASIC-PLUS), 5-38 to 5-42 
send call (BASIC-PLUS-2), 6-35 to 6-39 
Network diameter, 1-2 
Network File Transfer, 
See NFT/FAL 
Network Information and Control 
Exchange Protocol, 
See NICE 
Network program, 3-3, 3-4 
Network Services Protocol, 
See NSP 
NFT/FAL, 1-5, 4-6, 5-6, 5-35, 6-7, 6-32 
NICE, 3-6, 5-14, 5-16, 6-14, 6-15 
Node, 1-1 
address, 3-5, 5-12, 6-12 
adjacent, 1-1, 1-4 
alias, 3-5, 5-12, 6-12 
local, 1-1, 3-5 


name, 3-5, 5-12, 5-25, 5-66, 6-12, 6-23, 6-59 


nonrouting, 1-4 

parameters, 

See Local node parameters 

Phase II, 1-4 

remote, 1-1 

routing, 1-4 
Nonrouting node, 1-4 
NSP, 1-3, 1-4, 2-1 
NTCC call, 

See Connect Confirm Message 
NTCI call, 

See Connect Initiate Message 
NTCR call, 

See Connect Reject Message 
NTDI call, 

See Disconnect Message 
NTDM call, 

See Network Data Message 
NTEV call, 

See User events 
NTIN call, 

See Interrupt Message 
NTLA call, 

See Link Abort Message 
NTLN call, 

See Local node parameters 
NTLS call, 

See Link Service Message 


Object, 
automatic startup, 
See Automatic startup 
identification, 
See Receiver identity 
multiple copies, 
See Multiple copies of objects 
type code, 
See Receiver identity 
One-shot bit, 5-6, 6-7 
Opening devices, 5-2 


Parameters, 
in system calls (BASIC-PLUS), 5-2, 5-3 


in system calls (BASIC-PLUS-2), 6-2 to 6-4 


with DEFINE or SET OBJECT, 4-5 
Password, 5-27, 5-35, 5-68, 6-25, 6-32, 6-61 
Path, 1-2 
Path length, 1-2 


Pending message queue, 2-8, 3-3, 3-11, 3-12, 4-5, 


4-12 
Phase II, 1-4 
node, 1-4 
Phase III, 1-4 
Physical link, 1-1, 1-3, 1-5, 2-1 
Point-to-point lines, 1-5 


PPN, 5-26, 5-27, 5-35, 5-67, 5-68, 6-24, 6-25, 6-32, 


6-60, 6-61 

default, 3-5, 4-6, 5-12, 6-12 

Priority message, 
See Interrupt Message 

Privileged job, 4-6, 5-3 

Program, 
local, 3-3, 3-4 
network, 3-3, 3-4 
remote, 1-1 
source, 2-2 
target, 2-2 

Program-regulated flow control, 2-8, 4-14 
effect on DECnet/E programs, 4-14, 4-15 
message, 
See Message flow control 
segment, 
See Segment flow control ; 


selection, 3-7, 3-8, 4-14, 5-23 to 5-24, 5-31, 


5-65, 5-69, 6-21, 6-28, 6-58, 6-63 
use of Link Service Message, 4-14, 4-16 
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Project-programmer number, 
See PPN 
Protocols, 1-3 
DAP, 1-5 
DDCMP, 1-3, 1-5 
NICE, 3-6, 5-14, 5-16, 6-14, 6-15 
NSP, 1-3 
TRN, 1-3 


Q 


Queue, 

Data transmit, 4-9, 5-51, 5-55, 5-74, 6-47, 6-50, 
6-69 

Interrupt/Link Service, 4-9, 5-51, 5-55, 5-74, 
6-47, 6-50, 6-69 

management, 4-9 to 4-11 

message limit, 4-10 

pending message, 2-8, 3-3, 3-5, 3-11, 3-12, 4-5, 
4-12 


Reason code, B-1 
for Connect Reject, 3-9, 5-35, 5-70, 6-32, 6-65 
for Link Abort, 3-12, 5-77, 6-72 
Receive, 3-3 
job number, 5-60 
selective, 3-3, 3-11, 3-12, 5-59, 5-60, 6-52 to 
6-53, 6-54 
sleep, 3-3, 5-59, 5-61 to 5-62, 6-52, 6-55 
system calls (BASIC-PLUS), 5-58 to 5-77 
system calls (BASIC-PLUS-2), 6-52 to 6-56 
truncation of message, 3-3, 5-59, 5-61, 6-53, 
6-54 
Receive maximum, 3-7, 3-8, 3-10, 5-24, 5-32, 5-65, 
5-69, 6-21, 6-29, 6-58, 6-63 
Received formats, 
Connect Confirm Message 
(BASIC-PLUS), 5-69 
Connect Confirm Message 
(BASIC-PLUS-2), 6-63 
Connect Initiate Message 
(BASIC-PLUS), 5-65 to 5-66 
Connect Initiate Message 
(BASIC-PLUS-2), 6-58 
Connect Reject Message 
(BASIC-PLUS), 5-70 
Connect Reject Message 
(BASIC-PLUS-2), 6-65 
Disconnect Message (BASIC-PLUS), 5-76 
Disconnect Message (BASIC-PLUS-2), 6-71 
Interrupt Message (BASIC-PLUS), 5-72 
Interrupt Message (BASIC-PLUS-2), 6-67 
Link Abort Message (BASIC-PLUS), 5-77 


Link Abort Message (BASIC-PLUS-2), 6-72 
Link Service Message (BASIC-PLUS), 5-73 to 
5-75 
Link Service Message (BASIC-PLUS-2), 6-68 
to 6-69 
Local Data Message (BASIC-PLUS), 5-64 
Local Data Message (BASIC-PLUS-2), 6-57 
Network Data Message (BASIC-PLUS), 5-71 
Network Data Message (BASIC-PLUS-2), 6-66 
Receiver access, 
See Access 
Receiver ID Block, 
See RIB 
Receiver identity, 2-6, 3-4, 3-7 
consistency with access, 5-7, 6-7 
declaring, 4-1 
name, 3-4, 4-1, 5-5, 5-19, 6-5, 6-18 
object type code, 3-4, 4-2, 5-5, 6-5, A-1 
uniqueness, 4-2 
Receiver name, 
See Receiver identity 
RECORDSIZE, 5-2 
Remote link address, 
See RLA 
Remote link status flags, 5-74, 6-69 
Remote node, 1-1 
Remote program, 
definition, 1-1 
identification, 5-25 to 5-26, 5-66, 6-23 to 6-24, 
6-59 to 6-60 
Remove Receiver, 3-2, 3-5 
system call (BASIC-PLUS), 5-11 
system call (BASIC-PLUS-2), 6-11 
RIB, 3-5, 3-5, 4-2, 4-3, 4-12, 5-4, 6-5 
RLA, 2-3 
Routing, 1-3 
cost, 1-4 
hop, 1-2 
network diameter, 1-2 
path, 1-2 
path length, 1-2 
Routing node, 1-4 
RSTS/E system monitor, 1-4, 3-1 


S 


Segment, 
beginning of message, 5-39, 5-71, 6-35, 6-66 
definition, 4-14 
end of message, 4-15, 5-39, 5-71, 6-35, 6-66 
maximum size, 4-14 
request count, 4-15, 5-48, 5-74, 6-44, 6-69 
Segment flow control, 4-14 
Selective receives, 3-3, 3-11, 3-12, 5-59, 5-60, 6-52 
to 6-53, 6-54 
Send, 3-2 
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SET EXECUTOR, 4-10 
SET OBJECT, 4-5 
Sleep, 
in Declare Receiver, 5-6, 6-7 
in Receive, 3-3, 5-59, 6-52 
Sleep monitor call, 5-6, 6-7 
Source program, 2-2 
Strings, 
in system calls (BASIC-PLUS), 5-2 
in system calls (BASIC-PLUS-2), 6-3 
System buffer space, 2-8, 3-2, 3-4, 3-5, 5-7, 6-7 
System calls, 
arguments (BASIC-PLUS), 5-2, 5-3 
arguments (BASIC-PLUS-2), 6-2 to 6-4 
general form (BASIC-PLUS), 5-1 to 5-2 
general form (BASIC-PLUS-2), 6-1 to 6-2 
summary, 3-1 to 3-2 
System library, 6-4 
System manager, 1-4, 1-5, 2-10, 4-1, 4-3, 4-4, 
4-12, 4-7, 4-10, 5-14, 6-14 
SET EXECUTOR, 4-10 
SET OBJECT, 4-5 
Sleep, 
in Declare Receiver, 5-6, 6-7 
in Receive, 3-3, 5-59, 6-52 
Sleep monitor call, 5-6, 6-7 
Source program, 2-2 
Strings, 
in system calls (BASIC-PLUS), 5-2 
in system calls (BASIC-PLUS-2), 6-3 
System buffer space, 2-8, 3-2, 3-4, 3-5, 5-7, 6-7 
System calls, 
arguments (BASIC-PLUS), 5-2, 5-3 
arguments (BASIC-PLUS-2), 6-2 to 6-4 
general form (BASIC-PLUS), 5-1 to 5-2 
general form (BASIC-PLUS-2), 6-1 to 6-2 
summary, 3-1 to 3-2 
System library, 6-4 
System manager, 1-4, 1-5, 2-10, 4-1, 4-3, 4-4, 
4-12, 4-7, 4-10, 5-14, 6-14 


T 


Target program, 2-2 
Target string, 5-1 
Task Builder, 6-4 


Terminal Communications Utility, 
See TLK/LSN 
Timing, 
automatic startup, 4-5 
transmit queue management, 4-10 
TLK/LSN, 1-5 
Transmit maximum, 3-8, 3-9, 5-24, 5-32, 5-65, 
5-69, 6-22, 6-29, 6-58, 6-63 
Transmit queue management, 4-9 to 4-11 
effect on aborts, 4-10 
effect on DECnet/E programs, 4-10 
effect on disconnects, 4-10 
message limit, 4-10 
timing, 4-10 
Transport Protocol, 
See TRN 
TRN, 1-3, 1-5, 3-2 
Truncation of received messages, 3-3, 5-59, 5-61, 
6-53, 6-54 


UIC, 
See PPN 
ULA, 2-2, 3-12 
User data accompanying messages, 3-3, 3-9, 3-12 
User events, 3-2, 3-6 
class and type, 5-15, 6-14 
entity, 5-15, 6-15 
parameter data, 5-16, 6-15 
system call (BASIC-PLUS), 5-14 to 5-17 
system call (BASIC-PLUS-2), 6-14 to 6-16 
User Identification Code, 
See PPN 
User link address 
See ULA 


Virtual terminal, 


See NET 
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DECnet/E 

NETwork Programming in 
BASIC-PLUS and BASIC-PLUS-2 
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READER’S COMMENTS 
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 


company’s discretion. If you require a written reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 


Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement. 




















Did you find errors in this manual? If so, specify the error and the page number. 


Please indicate the type of user/reader that you most nearly represent. 











OC Assembly language programmer 
QO ——Higher-level language programmer 
O Occasional programmer (experienced) 
O User with little programming experience 
QO Student programmer 
O = Other (please specify) 
Nate 2 Date 
Organization 
Street 
City a State Zip Code 
or 
Country 
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